nCine::Application class
#include <nCine/Application.h>

Base class for the main entry point of an nCine application.

Owns the engine subsystems (graphics device, scene graph, input manager, viewport) and drives the game loop. Backend-specific subclasses such as MainApplication provide the platform glue.

Base classes

class Death::ITraceSink: Interface for sink to be used by logger writing to it.

Derived classes

class AndroidApplication: Main entry point and handler for Android applications.
class LibretroApplication: Application driven by a libretro frontend.
class MainApplication: Main entry point and event loop driver for standard (desktop) applications.
class UwpApplication: Main entry point and handler for UWP (Universal Windows Platform) applications.

Public types

struct RenderingSettings: Rendering settings that can be changed at run-time.
struct GuiSettings: GUI settings (for ImGui) that can be changed at run-time.
enum class Timings { PreInit, InitCommon, AppInit, BeginFrame, UpdateVisitDraw, Update, PostUpdate, Visit, Draw, ImGui, EndFrame, Audio, Present, Wait, Count }: Timings for profiling.

Public static functions

static auto GetDeviceHostname() -> String: Returns the name of the device the application is running on.

Constructors, destructors, conversion operators

Application() protected
~Application() protected

Public functions

auto GetAppConfiguration() const -> const AppConfiguration&: Returns the configuration used to initialize the application.
auto GetRenderingSettings() -> RenderingSettings&: Returns the run-time rendering settings.
auto GetGuiSettings() -> GuiSettings&: Returns run-time GUI settings.
auto GetDebugOverlaySettings() -> IDebugOverlay::DisplaySettings&: Returns debug overlay settings.
auto GetTimings() const -> StaticArrayView<(std::int32_t) Timings::Count, const float>: Returns all timings.
auto GetGfxDevice() -> IGfxDevice&: Returns the graphics device instance.
auto GetRootNode() -> SceneNode&: Returns the root of the transformation graph.
auto GetScreenViewport() -> Viewport&: Returns the screen viewport.
auto GetInputManager() -> IInputManager&: Returns the input manager instance.
auto GetFrameCount() const -> std::uint32_t: Returns the total number of frames already rendered.
auto GetTimeMult() const -> float: Returns a factor that represents how long the last frame took relative to the desired frame time.
auto GetFrameTimer() const -> const FrameTimer&: Returns the frame timer interface.
auto GetWidth() const -> std::int32_t: Returns the drawable screen width as an integer number.
auto GetHeight() const -> std::int32_t: Returns the drawable screen height as an integer number.
auto GetResolution() const -> Vector2i: Returns the drawable screen resolution as a Vector2i object.
void ResizeScreenViewport(std::int32_t width, std::int32_t height): Resizes the screen viewport, if exists.
auto ShouldSuspend() -> bool: Returns whether the application should currently be suspended.
auto GetAutoSuspension() const -> bool: Returns the value of the auto-suspension flag (the application will be suspended when it loses focus).
void SetAutoSuspension(bool autoSuspension): Sets the auto-suspension flag value.
void Quit() virtual: Raises the quit flag.
auto ShouldQuit() const -> bool: Returns the quit flag value.
auto HasFocus() const -> bool: Returns the focus flag value.
auto GetDataPath() const -> const String&: Returns the path for the application to load data from.
auto EnablePlayStationExtendedSupport(bool enable) -> bool virtual: Switches PS4 and PS5 controllers to use extended protocol which enables rumble and other features.
auto GetUserName() -> String virtual: Returns the username of the logged-in user.
auto OpenUrl(StringView url) -> bool virtual: Opens the specified URL in a default web browser.
auto CanShowScreenKeyboard() -> bool virtual: Returns true if screen (software) keyboard is supported and ShowScreenKeyboard() should succeed.
auto IsScreenKeyboardVisible() -> bool virtual: Returns true if the screen (software) keyboard is currently shown, always false if it cannot be queried.
auto ToggleScreenKeyboard() -> bool virtual: Toggles the screen (software) keyboard.
auto ShowScreenKeyboard(Containers::StringView initialText = {}, Containers::Function<void(Containers::StringView)>&& onCompleted = {}) -> bool virtual: Shows the screen (software) keyboard.
auto HideScreenKeyboard() -> bool virtual: Hides the screen (software) keyboard.
void AttachTraceTarget(Containers::StringView targetPath, bool archivePrevious = true): Adds the specified target as a sink for tracing.
void SetCrashDumpDirectory(Containers::StringView path): Overrides the base directory where crash memory dumps are written; no-op if crash handling is not enabled.
void Vibrate(std::int32_t milliseconds) virtual: Vibrates the device for the specified duration in milliseconds; no-op if not supported.
void ShowStatusBar() virtual: Shows the system status bar (if supported).
void HideStatusBar() virtual: Hides the system status bar (if supported).

Protected functions

void PreInitCommon(std::unique_ptr<IAppEventHandler> appEventHandler): Must be called as early as possible during the application startup.
void InitCommon(): Must be called before giving control to the application.
void Step(): Processes a single step of the game loop and renders a frame.
void ShutdownCommon(): Must be called before exiting to shut down the application.
void Suspend(): Called when the application gets suspended.
void Resume(): Called when the application resumes execution.
void SetFocus(bool hasFocus) virtual: Sets the focus flag.
void InitializeTrace(): Attaches the trace sink.
void ShutdownTrace(): Detaches the trace sink and closes the log file.
void OnTraceReceived(TraceLevel level, std::uint64_t timestamp, StringView threadId, StringView functionName, StringView content) override: Called when a new trace entry is received and should be written to the sink destination.
void OnTraceFlushed() override: Called when all buffers of the sink should be flushed immediately.

Constants

static char const * ConsoleTarget constexpr: Can be used in AttachTraceTarget() to attach to a console.

Enum documentation

enum class nCine::Application::Timings

Timings for profiling.

Everything from BeginFrame on is measured again every frame, but only while something reads the result - always in a build with NCINE_PROFILING, otherwise only while FrameStatistics collects.

Function documentation

static String nCine::Application::GetDeviceHostname()

Returns the name of the device the application is running on.

The host name wherever the platform has one - the computer name on Windows, gethostname() on the POSIX systems, the nickname the console was given in its settings on the Wii and the Switch. A console with no name of its own answers with another identifier that is stable for the device, formatted as text: the Android ID, the WLAN MAC address of the PlayStation Portable, the OpenPSID of the PS Vita and the PlayStation 3, the i.Link ID of the PlayStation 2, the system ID the BIOS keeps on the Dreamcast. Empty where nothing of the kind exists (GameCube, Nintendo 64, web) or when the query fails.

bool nCine::Application::ShowScreenKeyboard(Containers::StringView initialText = {}, Containers::Function<void(Containers::StringView)>&& onCompleted = {}) virtual

Shows the screen (software) keyboard.

Two kinds of platform answer this, and a caller that wants to work on both has to serve both. Where the keyboard is an overlay that feeds keystrokes (Windows, Android) it types into whatever has focus and the text arrives as IInputEventHandler::OnTextInput() events, exactly as a real keyboard would; initialText and onCompleted are unused there. Where it is a modal editor that collects a whole string (the PS Vita's IME) there are no keystrokes to deliver: initialText seeds the editor with what the field already holds, and onCompleted is invoked once with the finished string, which REPLACES that field rather than appending to it. It is not invoked at all if the user cancels.

So pass both, keep handling OnTextInput, and the field ends up right either way.

void nCine::Application::AttachTraceTarget(Containers::StringView targetPath, bool archivePrevious = true)

Adds the specified target as a sink for tracing.

Opening the file discards what the previous session left in it, so unless archivePrevious is false that content is first appended to "<targetPath>.gz" - a plain gzip file holding one member per session, oldest first, trimmed from the front once it outgrows its limit. Pass false where the path came from the user, who asked for that one file and nothing beside it.

void nCine::Application::InitializeTrace() protected

Attaches the trace sink.

Idempotent, so an entry point should call it as early as it has an application object - everything it does afterwards can then report through the ordinary LOG* macros. PreInitCommon() calls it as well, for the entry points that cannot get there any sooner.

nCine::Application class #include <nCine/Application.h>