Unigine::CustomApp Class

#include "AppSystemLogic.h"

#include <UnigineCustomApp.h>
#include <UnigineImage.h>

using namespace Unigine;


int AppSystemLogic::init() {

	// set a custom icon for the application window
	ImagePtr icon = Image::create("textures/window_icon.png");
	CustomApp::setIcon(icon);

	// set a custom title for the application window
	CustomApp::setTitle("Custom Window Title");

	return 1;
}

int AppSystemLogic::update() {
	
	// get an image for the mouse pointer
	ImagePtr mouse = Image::create();
	mouse->load("textures/mouse_pointer.png");
	// resize the image to make it square
	mouse->resize(mouse->getWidth(),mouse->getWidth());
	if (mouse->isLoaded() && mouse->getFormat() == Image::FORMAT_RGBA8)
	{
		// set the image for the OS mouse pointer
		CustomApp::setMouseCursor(mouse->getPixels(), mouse->getWidth());
		// show the OS mouse pointer
		CustomApp::setMouseCursorSystem(1);
	}
	
	return 1;
}

#include "AppWorldLogic.h"

#include <UnigineCustomApp.h>
#include <UnigineEditor.h>
#include <UnigineGame.h>
#include <UnigineGui.h>
#include <UnigineNode.h>
#include <UniginePlayers.h>

using namespace Unigine;

// declare a player pointer
PlayerPersecutorPtr player;

int AppWorldLogic::init() {
	
	// update the application constantly
	CustomApp::setBackgroundUpdate(1);
	// get a node
	NodePtr node = World::getNodeByName("material_ball");
	// create a new persecutor
	player = PlayerPersecutor::create();
	// set the obtainde node as the target one
	player->setTarget(node);
	// set player's settings
	player->setAnchor(Math::vec3(0, 0, 0.45f));
	player->setPhiAngle(-130.0f);
	player->setMinDistance(0.3f);
	player->setMaxDistance(20.0f);
	player->setDistance(5.0f);
	player->setFov(35.0f);
	// set the player to the Game Camera viewport
	Game::setPlayer(player);

	return 1;
}

int AppWorldLogic::update() {

	// change the distance between the player and the target node on mouse wheel scrolling
	int scroll_delta = CustomApp::getMouseAxis(CustomApp::AXIS_Y);
	if (scroll_delta != 0) {
		float f_scroll_delta = scroll_delta / 30.0f;
		player->setDistance(player->getDistance() - f_scroll_delta);
	}

	// zoom the camera in or out when the right mouse button is pressed and the mouse is moved backward/forward
	if (CustomApp::getMouseButton() == CustomApp::BUTTON_RIGHT) {
		float mouse_delta = (Gui::get()->getMouseDY() + Gui::get()->getMouseDX()) / 500.0f;
		player->setDistance(player->getDistance() - mouse_delta);
	}

	return 1;
}

App Class

Members

---

protected CustomApp ( ) #

int isActive ( ) #

Returns the value indicating if the current application is active (i.e. in focus). The function will always return 1, if the window update mode is set to 1.

Return value

1 if application is active; otherwise, 0.

int isLegacyMode ( ) const#

Returns a value indicating if rendering during the Engine's initialization stage is disabled for the application. Engine's boot screen requires rendering to be performed at the Engine's initialization stage. Certain applications do not support rendering in the init() by design. To ensure stable operation for such apps you can disable render-during-init functionality by setting the legacy mode. Thus, the boot screen won't be displayed for these applications.

Return value

1 if rendering during the Engine's initialization stage is disabled for the application; otherwise, 0.

void setClipboard ( const char * str ) #

Updates the contents of the system clipboard.

Arguments

• const char * str - Contents to set.

const char * getClipboard ( ) #

Retrieves the contents of the system clipboard.

Return value

Contents of the system clipboard.

void * getD3D11Context ( ) #

Returns a pointer to the existing ID3D11DeviceContext interface.

void * getD3D11Device ( ) #

Returns a pointer to the existing ID3D11Device interface.

Return value

ID3D11Device interface pointer.

int isD3D11Initialized ( ) #

Returns the status of the Direct3D11 render.

Return value

1 if the render is initialized; otherwise, 0.

int isDone ( ) #

Returns a value indicating if the application is closed.

Return value

1 if the application is closed; otherwise, 0.

int getFlags ( ) #

Returns the video mode flags set for the application.

Return value

Video mode flags: DESTROY, RESIZABLE, FULLSCREEN, etc.

float getFps ( ) #

Returns the application FPS counter value.

Return value

Application FPS counter value.

float getMinFps ( ) #

Returns the minimum FPS counter value for the last 600 frames.

Return value

Minimum FPS counter value for the last 600 frames.

float getMaxFps ( ) #

Returns the maximum FPS counter value for the last 600 frames.

Return value

Maximum FPS counter value for the last 600 frames.

float getMeanFps ( ) #

Returns the average FPS counter value for the last 600 frames.

Return value

Average FPS counter value for the last 600 frames.

int isGLInitialized ( ) #

Returns the status of the OpenGL renderer.

Return value

1 if the OpenGL render is initialized; otherwise, 0.

void * getHandle ( ) #

Returns a pointer to the application handle.

Return value

Pointer to the application handle.

void setHeight ( int value ) #

Sets the new height for the application window. The height is specified for the window inside and doesn't include the window borders.

Arguments

• int value - Application window height, in pixels.

int getHeight ( ) #

Returns the current height of the application window. The returned value is the window inside height without borders.

Return value

Current height of the application window, in pixels.

int setIcon ( const Ptr<Image> & icon ) #

Sets an icon for the application window. The image must be of the square size and RGBA8 format.

Arguments

• const Ptr<Image> & icon - Image to be set as application's icon.

Return value

1 if the icon is set successfully; otherwise, 0.

float getIFps ( ) #

Returns an inverse value of the application FPS counter.

Return value

Inverse value of the application FPS counter (1/FPS).

const char * getKeyName ( int key ) #

Returns a name of the given key.

Arguments

• int key - Key in one of the following formats:
  • Character format (for example, 'a')
  • Standard ASCII key code (for example, 97)
  • One of KEY_* variables

Return value

Key name.

void setKeyState ( int key, int state ) #

Sets the keyboard key state (pressed or not pressed).

Arguments

• int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.
• int state - Key state: 1 to set the button pressed; 0 to set the button not pressed.

int getKeyState ( int key ) #

Returns the keyboard key state (pressed or not pressed).

Arguments

• int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control button see KEY_* variables.

Return value

1 if the key is pressed; otherwise, 0.

void setMouse ( int x, int y ) #

Sets a mouse pointer to the specified position in the coordinate system of the application window.

Arguments

• int x - X coordinate of the mouse pointer.
• int y - Y coordinate of the mouse pointer.

void setMouseAxis ( int axis, int value ) #

Sets the mouse wheel delta along the specified axis. The delta value is changed when scrolling the mouse wheel horizontally (APP_AXIS_X) or vertically (APP_AXIS_Y).

Arguments

• int axis - Mouse axis. Possible values are AXIS_X, AXIS_Y.
• int value - Mouse wheel delta.

int getMouseAxis ( int axis ) #

Returns the current mouse wheel delta along the specified axis. The delta value is changed when scrolling the mouse wheel horizontally (AXIS_X) or vertically (AXIS_Y).

Arguments

• int axis - Mouse axis. Possible values are AXIS_X, AXIS_Y.

Return value

Mouse wheel delta regarding the last wheel position.

void setMouseButton ( int button ) #

Simulates pressing of the specified mouse buttons.

Arguments

• int button - Mouse buttons to be pressed. Possible values are BUTTON_*.

int getMouseButton ( ) #

Returns the current states of all mouse buttons. Each bit of the returned bit mask will specify the state of the buttons in the following order:

1. BUTTON_LEFT = 1 << 0
2. BUTTON_MIDDLE
3. BUTTON_RIGHT
4. BUTTON_DCLICK
5. BUTTON_AUX_0
6. BUTTON_AUX_1
7. BUTTON_AUX_2
8. BUTTON_AUX_3

Return value

A bit mask that stores current states of all mouse buttons (pressed or not pressed).

const char * getMouseButtonName ( int button ) #

Returns a name of the given button.

Arguments

• int button - One of BUTTON_* variables.

Return value

Button name.

int getMouseButtonState ( int button ) #

Returns a state of the specified button (pressed or not pressed). If several buttons are specified, the function will return the state of the first pressed button (if any); if no buttons are pressed, the function will return 0.

Arguments

• int button - One of BUTTON_* variables

Return value

1 if al least one of the specified buttons is pressed; otherwise, 0.

int getMouseX ( ) #

Returns the current X coordinate of the mouse pointer in the coordinate system of the application window.

Return value

X coordinate of the mouse pointer.

int getMouseY ( ) #

Returns the current Y coordinate of the mouse pointer in the coordinate system of the application window.

Return value

Y coordinate of the mouse pointer.

const char * getName ( ) #

Returns a name of the graphics API used for application rendering.

Return value

One of the following values:

• opengl for OpenGL
• direct3d11 for DirectX 11
• NULL if no graphics API is used for application rendering

int isNULLInitialized ( ) #

Returns a value indicating whether the NULL renderer is initialized.

Return value

1 if the renderer is initialized; otherwise, 0.

int getNumTouches ( ) #

Returns the number of touches. The maximum number of touches is 16.

Return value

Number of touches.

int setPosition ( int x, int y ) #

Sets the window position.

Arguments

• int x - X coordinate of the upper-left corner of the window.
• int y - Y coordinate of the upper-left corner of the window.

Return value

1 if the position of the window is set successfully; otherwise, 0.

int getPositionX ( ) #

Returns the X coordinate of the upper-left corner of the window.

Return value

X coordinate of the upper-left corner of the window.

int getPositionY ( ) #

Returns the Y coordinate of the upper-left corner of the window.

Return value

Y coordinate of the upper-left corner of the window.

int setTitle ( const char * title ) #

Sets a title for the application window.

Arguments

• const char * title - Window title.

Return value

1 if the title is set successfully; otherwise, 0.

int getTouchX ( int touch ) #

Returns the X coordinate of the touch in the coordinate system of the application window.

Arguments

• int touch - The touch number.

Return value

X coordinate of the touch.

int getTouchY ( int touch ) #

Returns the Y coordinate of the touch in the coordinate system of the application window.

Arguments

• int touch - The toucn number.

Return value

Y coordinate of the touch.

int isBackgroundUpdate ( ) #

Returns the current window update mode (the value indicating whether the application is updated when the window is hidden).

Return value

1 if the update cycle is constantly repeated; otherwise, 0.

void setBackgroundUpdate ( int update ) #

Sets the value indicating whether the application widow is updated when the window is hidden or out of focus (rendering frames in background). By default your UNIGINE application stops rendering frames and updating its main window, when it window goes out of focus (e.g. user switches to another window). Setting the update mode to 1 enables constant rendering regardless of whether the application window is focused or in the background.

Arguments

• int update - Window update mode: 1 for constantly repeating update cycle (i.e. the application is updated if the window is hidden or out of focus); otherwise, 0.

int setVideoMode ( int width, int height, int flags = 0 ) #

Sets a video mode and initializes the application.

Arguments

• int width - Video width in pixels.
• int height - Video height in pixels.
• int flags - Video mode flags: DESTROY, RESIZABLE, FULLSCREEN, FULLWINDOW, VSYNC, DEBUG_CONTEXT, BREAK_ON_ERROR.

Return value

1 if the video mode is set and the application is initialized successfully; otherwise, 0.

const char * getVideoModeName ( ) #

Returns the name of the current video mode.

Return value

Returns the name of the current video mode.

void setWidth ( int value ) #

Sets the new width of the application window. The width is specified for the window inside part and doesn't include the window borders.

Arguments

• int value - Window width, in pixels.

int getWidth ( ) #

Returns the current application window width. The returned value is the window inside part width without borders.

Return value

Window width, in pixels.

void buttonPress ( int button ) #

Application notifies the engine that the specified mouse button is pressed.

Arguments

• int button - One of the BUTTON_* variables.

void buttonRelease ( int button ) #

Application notifies the engine that the specified mouse button is released.

Arguments

• int button - One of the BUTTON_* variables.

int clearKeyState ( int key ) #

Returns the key state and clears it to 0 (not pressed). This function allows returning the key state only once even if it is kept pressed over several frames.

Arguments

• int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.

Return value

1 if the key is pressed, and this function was not called previously in the current frame; otherwise, 0.

int clearMouseAxis ( int axis ) #

Returns the current mouse wheel position delta and clears it to 0.

Arguments

• int axis - Mouse wheel axis. Possible values are AXIS_X, AXIS_Y.

Return value

Mouse wheel delta regarding the last mouse wheel position.

int clearMouseButtonState ( int button ) #

Returns the button state and clears it to 0 (not pressed). This function allows returning the button state only once even if it is kept pressed over several frames. The function will return 1 if at least one of the specified buttons is pressed.

Arguments

• int button - Button. Possible values are BUTTON_*.

Return value

1 if at least one of the buttons is pressed, and this function was not called previously in the current frame; otherwise, 0.

int dialogMessage ( const char * title, const char * str, const char * flags = 0 ) #

Creates a system modal message dialog. Since the dialog is modal, all other actions are stopped until this function returns a value.

Arguments

• const char * title - Title of the dialog window.
• const char * str - Content of the dialog window.
• const char * flags - Dialog window flags. The argument accepts a string with names of buttons. The following combinations are available:
  • Oc or oC - OK, Cancel.
  • Yn or yN - Yes, No
  • ynC, yNc or Ync - Yes, No, Cancel
  Notice

  The uppercase letter indicates which button will be in focus.
  If you send any other combination, only the OK button will appear in the window.

Return value

The function returns one of the following values:

• 1 if the OK button has been pressed.
• 2 if the Yes button has been pressed.
• -1 if the No button has been pressed.
• 0 if the Cancel button has been pressed.

void doRender ( ) #

The engine requests to call the render() function. The application can ignore this request if it handles the main loop by itself.

void doSwap ( ) #

The engine requests to call the swap() function. The application can ignore this request if it handles the main loop by itself.

void doUpdate ( ) #

The engine requests to call the update() function. Application can ignore this request if it handles the main loop by itself.

void exit ( ) #

The engine requests to exit the application.

int initD3D11 ( void * adapter, void * device, void * context, int debug = 0 ) #

Initializes the Direct3D11 render. This function should be called when the Direct3D11 device is ready for rendering.

Arguments

• void * adapter - Pointer to the IDXGIAdapter interface.
• void * device - Pointer to the ID3D11Device interface.
• void * context - Pointer to ID3D11DeviceContext interface.
• int debug - Debug output flag. Use 1 to enable debug output, 0 to disable it.

Return value

1 if the Direct3D11 render is initialized successfully; otherwise, 0.

int initGL ( void * context, int debug = 0 ) #

Initializes the OpenGL render. This function should be called when OpenGL context is created.

Arguments

• void * context - Pointer to OpenGL Context interface.
• int debug - Debug output flag. Use 1 to enable debug output, 0 to disable it.

Return value

1 if the render is initialized successfully; otherwise, 0.

int initNULL ( ) #

Initializes the NULL renderer: nothing is rendered onto the screen. This mode is used, for example, for servers in case of playing over the network.

Return value

1 if the renderer is initialized successfully; otherwise, 0.

void keyPress ( unsigned int key ) #

Application notifies the engine that the specified key on a keyboard is pressed.

Arguments

• unsigned int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.

void keyPressUnicode ( unsigned int key ) #

Application notifies the engine that the specified key is pressed.

Arguments

• unsigned int key - Unicode symbol.

void keyRelease ( unsigned int key ) #

Application notifies the engine that the specified key on a keyboard is released.

Arguments

• unsigned int key - Key ID. Possible values can be in range [0;255], which are standard ASCII code symbols, or in range [KEY_ESC;KEY_F12], which are used for control buttons. For full list of control buttons see KEY_* variables.

void render ( ) #

Application requests the engine to render.

int shutdownD3D11 ( ) #

Shuts down the Direct3D11 render. This function should be called when the Direct3D11 device is released.

Return value

1 if the Direct3D11 render is shut down successfully; otherwise, 0.

int shutdownGL ( ) #

Shuts down the OpenGL render. This function should be called when OpenGL context is destroyed.

Return value

1 if the render is shut down successfully; otherwise, 0.

int shutdownNULL ( ) #

Shuts down the NULL renderer.

Return value

1 if the renderer is shut down successfully; otherwise, 0.

void startFps ( ) #

Starts the FPS counter if it was stopped. All function calls are placed into a stack, so the number of calls to this function should correspond to the number of calls to the stopFps() function.

void stopFps ( ) #

Stops the FPS counter. This function should be called if application window is hidden or some heavy non-rendering tasks are processing. All function calls are placed into a stack, so the number of calls to this function should correspond to the number of calls to the startFps() function.

void swap ( ) #

Application requests the engine to swap.

void update ( ) #

Application requests the engine to update.

Ptr<RenderContext> createContext ( ) #

Creates a rendering context depending on the graphics API used for application rendering.

Return value

RenderContext smart pointer.

Ptr<RenderContext> initGLContext ( ) #

Initializes an OpenGL rendering context.

Return value

RenderContext smart pointer.

Ptr<RenderContext> initD3D11Context ( ) #

Initializes a D3D11 rendering context.

Return value

RenderContext smart pointer.

void * getGLContext ( ) #

Returns the pointer to the OpenGL context.

Return value

OpenGL context pointer.

int getGLVersionMajor ( ) #

Returns the major version number of the supported OpenGL API.

Return value

OpenGL API major version number.

int getGLVersionMinor ( ) #

Returns the minor version number of the supported OpenGL API.

Return value

OpenGL API minor version number.

void setCustomSwapBuffersCallback ( CallbackBase * callback ) #

Sets a callback to subscribe for an event to take place instead of swapping from the back buffer to the front one. So you can add your custom logic just before, right after or even instead of the buffer swap operation. The callback signature is as follows: Logic of these three pointers is determined by the current graphics API:

• DirectX on Windows: arg1 - ID3D11Device, arg2 - ID3D11DeviceContext, arg3 - IDXGISwapChain
• OpenGL on Windows: arg1 - HDC
• OpenGL on Linux: arg1 - Display, arg2 - GLXDrawable

Here is an example that uses VSync even if -video_vsync 0:

Arguments

• CallbackBase * callback - Callback pointer.

CallbackBase * getCustomSwapBuffersCallback ( ) #

Returns the current buffer swap callback function set for the application.

Return value

Callback pointer.

void set ( CustomApp * app ) #

Sets the custom application interface.

Arguments

• CustomApp * app - Pointer to the custom application interface.

void setMouseCursorSkinCustom ( const Ptr<Image> & image ) #

Sets a custom image to be used for the mouse cursor.

Arguments

• const Ptr<Image> & image - Image containing pointer shapes to be set for the mouse cursor (e.g., select, move, resize, etc.).

void setMouseCursorSkinSystem ( ) #

Sets the default Engine cursor skin (pointer shapes like select, move, resize, etc.).

void setMouseCursorCustom ( const Ptr<Image> & image, int x = 0, int y = 0 ) #

Sets a custom image for the OS mouse cursor. The image must be of the square size and RGBA8 format.

Arguments

• const Ptr<Image> & image - Cursor image to be set.
• int x - X coordinate of the cursor's hot spot.
• int y - Y coordinate of the cursor's hot spot.

void clearMouseCursorCustom ( ) #

Clears the custom mouse cursor set via the setMouseCursorCustom() method.

void updateMouseCursor ( ) #

Updates the mouse cursor. This method should be called after making changes to the mouse cursor to apply them all together. After calling this method the cursor shall be updated in the next frame.

bool dialogWarning ( const char * title, const char * warning ) #

Displays a warning dialog with the specified title and text.

Arguments

• const char * title - Title of the warning dialog to be displayed.
• const char * warning - Warning message text to be displayed.

Return value

true if the message is displayed successfully; otherwise, false.

bool dialogError ( const char * title, const char * error ) #

Displays an error dialog with the specified title and text.

Arguments

• const char * title - Title of the error dialog to be displayed.
• const char * error - Error message text to be displayed.

Return value

true if the message is displayed successfully; otherwise, false.

virtual void onFileSystemInitialized ( ) #