Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Unigine::App Class

Header:#include <UnigineApp.h>

This class contains functions to control the Unigine application graphic context, which includes:

  • Update parameters.
  • Events of the controls (keyboard, mouse).
  • FPS.
  • Window parameters (height, width, name, etc.).

App Class

Members


App * get()

Returns a pointer to the App instance.

Return value

App instance.

int isActive()

Returns the value indicating if the current application is active.
Notice
The sounds will be automatically disabled, if the application is not active.

Return value

1 if application is active; otherwise - 0.

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

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

Arguments

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

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

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

Arguments

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

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.

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.

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).

int getFlags()

Returns the current video mode flags.

Return value

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

float getFps()

Returns the application FPS counter value.

Return value

Application FPS counter value.

float getFTime()

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

Return value

Application frame duration in seconds.

int setGamma(float gamma)

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

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

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 application window height.

Arguments

  • int value - Application window height, in pixels.

int getHeight()

Returns the current application window height.

Return value

Current application window height, in pixels.

int setIcon(uchar[] data)

Sets an icon for the application window.

Arguments

  • uchar[] data - An icon to be set.

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 a 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 APP_KEY_*variables

Return value

Key name.

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

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

Arguments

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

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

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

Arguments

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

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

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

Arguments

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

void setKeyState(int key, int state)

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 App:: Enumeration at the end of the article.
  • int state - Key state: 1 to set the button pressed; 0 to set the button unpressed.

int getKeyState(int key)

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 App:: Enumeration at the end of the article.

Return value

1 if the key is pressed; otherwise, 0.

void setMouse(int x, int y)

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.

void setMouseAxis(int axis, int value)

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.

int getMouseAxis(int axis)

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.

void setMouseButton(int arg1)

Sets the mouse button to be pressed.

Arguments

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

int getMouseButton()

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 App:: Enumeration at the end of the article.

Return value

Mouse button status.

const char * getMouseButtonName(int button)

Returns a name of a given button.

Arguments

Return value

Button name.

int getMouseButtonState(int button)

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 App:: Enumeration at the end of the article.

Return value

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

int setMouseCursor(uchar[] data, int x = 0, int y = 0)

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

Arguments

  • uchar[] data
  • int x
  • int y

Return value

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

void setMouseGrab(int arg1)

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

Arguments

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

int getMouseGrab()

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

Return value

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

void setMouseShow(int arg1)

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

Arguments

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

int getMouseShow()

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

Return value

1 if the OS mouse pointer is displayed; 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

Returns "opengl" for OpenGL, "opengles" for OpenGL ES, "direct3d11" for DirectX 11 or 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 is the renderer is initialized; otherwise, 0.

int getNumTouches()

Returns the number of touches.

Return value

Number of touches.

int setPosition(int x, int y)

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

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

int getPositionX()

Returns the window position.

Return value

Returns position of the left side of window.

int getPositionY()

Returns the window position.

Return value

Returns position of the top side of window.

int setTitle(const char * title)

Sets a title for the application window.

Arguments

  • const char * title - Window title to set.

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 toucn 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 setUpdate(int update)

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

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

int getUpdate()

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

Return value

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

int setVideoMode(int width, int height, int flags = 0, 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, FULLSCREEN, etc.
  • int refresh - Force refresh rate in Hz; if 0 is provided, default refresh rate is used.

Return value

1 if the video mode is set successfully and the application is also 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.

Arguments

  • int value - Window width, in pixels.

int getWidth()

Returns the current application window width.

Return value

Window width, in pixels.

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 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 App:: Enumeration at the end of the article.

int clearKeyState(int key)

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 App:: Enumeration at the end of the article.

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 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.

int clearMouseButtonState(int button)

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 App:: Enumeration at the end of the article.

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.

void destroy()

Application requests the engine to destroy.

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

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

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

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.
Notice
If you don't specify flags, the Oc combination will be used by default.

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 render() function. Application can ignore this request if it handles the main loop by itself.

void doSwap()

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

void doUpdate()

The engine requests to call 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)

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

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

int initGL()

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

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

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 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 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 App:: Enumeration at the end of the article.

void render()

Application requests the engine to render.

int restoreVideoMode()

Restores the video mode of the operating system.

Return value

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

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

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.

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 swap()

Application requests the engine to swap.

void update()

Application requests the engine to update.

int AXIS_X

Description

A mouse wheel is scrolled horizontally (along the X axis; a horizontal mouse wheel is required).

int AXIS_Y

Description

A mouse wheel is scrolled vertically (along the Y axis; a vertical mouse wheel is used).

int BUTTON_AUX_0

Description

A detected activity of the first auxiliary mouse button.

int BUTTON_AUX_1

Description

Detected activity belongs to the second auxiliary mouse button.

int BUTTON_AUX_2

Description

Detected activity belongs to the third auxiliary mouse button.

int BUTTON_AUX_3

Description

Detected activity belongs to the fourth auxiliary mouse button.

int BUTTON_DCLICK

Description

A mouse button is double-clicked.

int BUTTON_LEFT

Description

Detected activity belongs to the left mouse button.

int BUTTON_MIDDLE

Description

Detected activity belongs to the middle mouse button (scrolling wheel).

int BUTTON_RIGHT

Description

Detected activity belongs to the right mouse button.

int DEBUG_CONTEXT

Description

A debug context is enabled.

int DESTROY

Description

A fullscreen mode is destroyed.

int FULLSCREEN

Description

A fullscreen mode.

int FULLWINDOW

Description

A full window mode.

int KEY_ALT

Description

The ALT key is pressed.

int KEY_BACKSPACE

Description

The Backspace key is pressed.

int KEY_CAPS

Description

The Caps Lock key is pressed.

int KEY_CMD

Description

The Command key is pressed (for OS X).

int KEY_CTRL

Description

The Ctrl key is pressed.

int KEY_DELETE

Description

The Delete key is pressed.

int KEY_DOWN

Description

The Down Arrow key is pressed.

int KEY_END

Description

The End key is pressed.

int KEY_ESC

Description

The Esc key is pressed.

int KEY_F1

Description

The F1 key is pressed.

int KEY_F10

Description

The F10 key is pressed.

int KEY_F11

Description

The F11 key is pressed.

int KEY_F12

Description

The F12 key is pressed.

int KEY_F2

Description

The F2 key is pressed.

int KEY_F3

Description

The F3 key is pressed.

int KEY_F4

Description

The F4 key is pressed.

int KEY_F5

Description

The F5 key is pressed.

int KEY_F6

Description

The F6 key is pressed.

int KEY_F7

Description

The F7 key is pressed.

int KEY_F8

Description

The F8 key is pressed.

int KEY_F9

Description

The F9 key is pressed.

int KEY_HOME

Description

The Home key is pressed.

int KEY_INSERT

Description

The Insert key is pressed.

int KEY_LEFT

Description

The Left Arrow key is pressed.

int KEY_NUM

Description

The Num Lock key is pressed.

int KEY_PGDOWN

Description

The Page Down key is pressed.

int KEY_PGUP

Description

The Page Up key is pressed.

int KEY_RETURN

Description

The Enter (Return) key is pressed.

int KEY_RIGHT

Description

The Right Arrow key is pressed.

int KEY_SCROLL

Description

The Scroll Lock key is pressed.

int KEY_SHIFT

Description

The Shift key is pressed.

int KEY_TAB

Description

The Tab key is pressed.

int KEY_UP

Description

The Page Up key is pressed.

int NUM_AXES

Description

Number of axes, along which a mouse wheel can be scrolled.

int NUM_KEYS

Description

Detected number of keyboard keys.

int NUM_TOUCHES

Description

The number of the deteched touches (for touch-screen controls).

int RESIZABLE

Description

A resizable window.

int VSYNC

Description

Vertical syncronization.
Last update: 2017-07-03