Unigine::App Class

Unigine Application.

To use this class, include the UnigineApp.h file.

Unigine::App Class

Members

---

App ()

Constructor.

virtual ~App ()

Virtual destructor.

virtual void * getHandle () =0

Returns a pointer to the application handle.

Return value

Pointer to the application handle.

virtual const char * getName () =0

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

Return value

Returns "opengl" for OpenGL, "opengles" for OpenGL ES, "direct3d11" for DirectX 11 or NULL if no graphics API is used for application rendering.

virtual int setPosition (int x, int y) =0

Sets the window position.

Arguments

• int x - Position of the left side of the window.
• int y - Position of the top side of the window.

Return value

Returns 1 if the video mode is restored successfully; otherwise, 0.

virtual int getPositionX () =0

Returns the window position.

Return value

Returns position of the left side of window.

virtual int getPositionY () =0

Returns the window position.

Return value

Returns position of the top side of window.

virtual int setVideoMode (int width, int height, int flags, int refresh) =0

Sets a video mode and initializes application.

Arguments

• int width - Video width in pixels.
• int height - Video height in pixels.
• int flags - Video mode flags: DESTROY, RESIZABLE, FULSCREEN, etc. For full list of available flags see Unigine::App:: Enumeration at the end of the article.
• int refresh - Force refresh rate in Hz; if 0 is provided, default refresh rate is used.

Return value

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

virtual int restoreVideoMode () =0

Restores the video mode of the operating system.

Return value

Returns 1 if the video mode is restored successfully; otherwise, 0.

virtual int setUpdate (int update) =0

Sets the value indicating whether the application is updated when the window is hidden.

Arguments

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

Return value

Return 1 if the window update mode is set successfully; otherwise, 0.

virtual int setGamma (float gamma) =0

Sets the gamma correction value.

Arguments

• float gamma - Gamma correction value. If the 1.0f value is provided, no gamma correction is applied.

Return value

Returns 1 if the gamma correction value is set successfully; otherwise, 0.

virtual int setTitle (const char * title) =0

Sets a title for the application window.

Arguments

• const char * title - Window title to set.

Return value

Returns 1 if the title for the application window is set successfully; otherwise, 0.

virtual int setIcon (const unsigned char * data, int size) =0

Sets an icon for the application window.

Arguments

• const unsigned char * data - Pointer to a square RGBA8 image.
• int size - Size of a square icon image in pixels.

Return value

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

virtual int getWidth () =0

Returns the current video width.

Return value

Current video width in pixels.

virtual int getHeight () =0

Returns the current video height.

Return value

Current video height in pixels.

virtual int getFlags () =0

Returns the current video mode flags.

Return value

Video mode flags: DESTROY, RESIZABLE, FULSCREEN, etc. For full list of available flags see Unigine::App:: Enumeration at the end of the article.

virtual int getUpdate () =0

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

Return value

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

const char * getVideoModeName ()

Returns the name of the current video mode.

Return value

Returns the name of the current video mode.

virtual void setMouse (int x, int y) =0

Sets a mouse pointer to a given 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.

virtual void setMouseGrab (int grab) =0

Sets a value indicating if the mouse pointer is bound to the application window.

Arguments

• int grab - Grabbing parameter: 1 if the mouse pointer cannot leave the application window; otherwise, 0.

virtual void setMouseShow (int show) =0

Sets a value indicating if the operating system mouse pointer should be displayed.

Arguments

• int show - Display parameter: 1 if the OS mouse pointer should be displayed; 0 if the application cursor is used only.

virtual int setMouseCursor (const unsigned char * data, int size, int x, int y) =0

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

Arguments

• const unsigned char * data - Pointer to a square RGBA8 image.
• int size - Size of a square icon image in pixels.
• int x - X coordinate of the hotspot.
• int y - Y coordinate of the hotspot.

Return value

Returns 1 if the image is set successfully; otherwise, 0.

virtual int getMouseX () =0

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.

virtual int getMouseY () =0

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.

virtual int getMouseGrab () =0

Returns the current mouse grab parameter, which indicates if the mouse pointer is bound to the application window.

Return value

Returns 1 if the mouse pointer cannot leave the application window; otherwise, 0.

virtual int getMouseShow () =0

Returns the current mouse display parameter, which indicates if the the operating system pointer is displayed.

Return value

Returns 1 if the OS mouse pointer is displayed; otherwise, 0.

virtual void setMouseAxis (int axis, int value) =0

Sets the mouse axis position delta.

Arguments

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

virtual int getMouseAxis (int axis) =0

Returns the current mouse axis position delta.

Arguments

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

Return value

Mouse axis delta regarding the last mouse axis position, integer value.

virtual int clearMouseAxis (int axis) =0

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

Arguments

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

Return value

Mouse axis delta regarding the last mouse axis position, integer value.

virtual void setMouseButton (int button) =0

Sets the mouse button to be pressed.

Arguments

• int button - Mouse button to be pressed. Possible values are BUTTON_LEFT, BUTTON_RIGHT, etc. For full list of the values see Unigine::App:: Enumeration at the end of the article.

virtual int getMouseButton () =0

Returns the current states of all mouse buttons. Each bit of the returned bit mask will specify the state of the buttons (BUTTON_LEFT, BUTTON_MIDDLE, etc.) in the order specified in Unigine::App:: Enumeration at the end of the article.

Return value

Mouse button status.

virtual int getMouseButtonState (int button) =0

Returns the mouse button state.

Arguments

• int button - Button ID. Possible values are BUTTON_LEFT, BUTTON_RIGHT, etc. For full list of the values see Unigine::App:: Enumeration at the end of the article.

Return value

Returns 1 if the button is pressed; otherwise, 0.

virtual int clearMouseButtonState (int button) =0

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

Arguments

• int button - Button ID. Possible values are BUTTON_LEFT, BUTTON_RIGHT, etc. For full list of the values see Unigine::App:: Enumeration at the end of the article.

Return value

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

virtual int getNumTouches () =0

Returns the number of touches.

Return value

Number of touches.

virtual int getTouchX (int touch) =0

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

Arguments

• int touch - The toucn number.

Return value

X coordinate of the touch.

virtual int getTouchY (int touch) =0

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.

virtual void setKeyState (int key, int state) =0

Sets the keyboard key state.

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_NUM], which are used for control buttons. For full list of control button see Unigine::App:: Enumeration at the end of the article.
• int state - Key state: 1 to set the button pressed; 0 to set the button unpressed.

virtual int getKeyState (int key) =0

Returns the keyboard key state.

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_NUM], which are used for control buttons. For full list of control button see Unigine::App:: Enumeration at the end of the article.

Return value

Returns 1 if the key is pressed, 0 if not.

virtual int clearKeyState (int key) =0

Returns the keyboard key state and clear it to zero.

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_NUM], which are used for control buttons. For full list of control button see Unigine::App:: Enumeration at the end of the article.

Return value

Returns 1 if the key state is cleared; otherwise, 0.

virtual int isDone () =0

Returns a value indicating if the application is closed.

Return value

Returns 1 if the application is closed; otherwise, 0.

virtual void doUpdate () =0

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

virtual void doRender () =0

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

virtual void doSwap () =0

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

virtual void exit () =0

The engine requests to exit the application.

virtual void setClipboard (const char * str)

Updates the contents of the system clipboard.

Arguments

• const char * str - Contents to set.

virtual const char * getClipboard ()

Retrieves the contents of the system clipboard.

Return value

Contents of the system clipboard.

virtual int dialogMessage (const char * title, const char * str, const char * flags)

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. Accepts string with button names: "Oc" - "OK, cancel"; "Yn" - "YES, no"; "ynC"; "yes, no, CANCEL".

Return value

Returns 1 if the OK button is pressed; 0 if the Cancel button is pressed.

virtual int dialogFile (const char * title, char * name, int size, const char * filter, const char * flags)

Creates a system modal file 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.
• char * name - Current file name.
• int size - Size of the name buffer.
• const char * filter - File extension filter. Accepts dot-separated file extensions: ".tga.jpg.png.tif.psd"
• const char * flags - Dialog file flags. Accepts string: "o" - open file dialog; "s" - save file dialog; "d" - directory dialog.

Return value

Returns 1 if the OK button is pressed; 0 if the Cancel button is pressed.

int initGL ()

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

Return value

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

int shutdownGL ()

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

Return value

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

int isGLInitialized ()

Returns the status of the OpenGL render.

Return value

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

int initD3D11 (void * adapter, void * device, void * context)

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.

Return value

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

int shutdownD3D11 ()

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

Return value

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

int isD3D11Initialized ()

Returns the status of the Direct3D11 render.

Return value

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

void * getD3D11Device ()

Returns a pointer to the existing ID3D11Device interface.

void * getD3D11Context ()

Returns a pointer to the existing ID3D11DeviceContext interface.

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 is the renderer is initialized successfully; otherwise, 0.

int shutdownNULL ()

Shuts down the NULL renderer.

Return value

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

int isNULLInitialized ()

Returns a value indicating whether the NULL renderer is initialized.

Return value

1 is the renderer is initialized; otherwise, 0.

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 stack, so the number of calls to this function should correspond to the number of calls to the startFps() function.

void startFps ()

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

float getFps ()

Returns the application FPS counter value.

Return value

Application FPS counter value.

float getIFps ()

Returns an inverse value of the application FPS counter.

Return value

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

float getFTime ()

Returns time spent between a previous update and a current one.

Return value

Application frame duration in seconds.

void setFilter (float filter)

Sets a filter for the FPS counter value. If the filter value is 0, filtering is disabled and the current FPS value is always shown.

Arguments

• float filter - Filter value in range [0;1). The default value is 0.9f (10 percent of the current FPS is taken into account).

void destroy ()

Application requests the engine to destroy.

void update ()

Application requests the engine to update.

void render ()

Application requests the engine to render.

void swap ()

Application requests the engine to swap.

void buttonPress (int button)

Application notifies the engine that a mouse button is pressed.

Arguments

• int button - Button ID. Possible values are BUTTON_LEFT, BUTTON_RIGHT, etc. For full list of the values see Unigine::App:: Enumeration at the end of the article.

void buttonRelease (int button)

Application notifies the engine that a mouse button is released.

Arguments

• int button - Button ID. Possible values are BUTTON_LEFT, BUTTON_RIGHT, etc. For full list of the values see Unigine::App:: Enumeration at the end of the article.

void keyPress (unsigned int key)

Application notifies the engine that a 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_NUM], which are used for control buttons. For full list of control button see Unigine::App:: Enumeration at the end of the article.

void keyRelease (unsigned int key)

Application notifies the engine that a 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_NUM], which are used for control buttons. For full list of control button see Unigine::App:: Enumeration at the end of the article.

void keyPressUnicode (unsigned int key)

Application notifies the engine that a key is pressed.

Arguments

• unsigned int key - Unicode symbol ID.

void setButtonPressFunc (int(*)(int button) func)

Application event which is called on button press. The engine will stop event processing if the event function Returns 1.

Arguments

• int(*)(int button) func - Event function pointer.

void setButtonReleaseFunc (int(*)(int button) func)

Application event which is called on button release. The engine will stop event processing if the event function Returns 1.

Arguments

• int(*)(int button) func - Event function pointer.

void setKeyPressFunc (int(*)(unsigned int key) func)

Application event which is called on key press. The engine will stop event processing if the event function Returns 1.

Arguments

• int(*)(unsigned int key) func - Event function pointer.

void setKeyReleaseFunc (int(*)(unsigned int key) func)

Application event which is called on key release. The engine will stop event processing if the event function Returns 1.

Arguments

• int(*)(unsigned int key) func - Event function pointer.

void setKeyPressUnicodeFunc (int(*)(unsigned int key) func)

Application event which is called on unicode key press. The engine will stop event processing if the event function Returns 1.

Arguments

• int(*)(unsigned int key) func - Event function pointer.

static void set (App * app)

Sets a pointer to the external application to the engine.

Arguments

• App * app - App pointer.

static App * get ()

Returns a pointer to the existing App.

Return value

Pointer to the existing App.

---

Unigine::App::anonymous_0 Enumeration

Unigine::App::anonymous_1 Enumeration

Unigine::App::anonymous_2 Enumeration

Unigine::App::anonymous_3 Enumeration

Unigine::App::anonymous_4 Enumeration