Details

The AppCore API is a convenient windowing system for desktop platforms built on top of the Ultralight renderer.

It automatically sets up the Renderer, creates a run loop, and handles all window creation, painting, and platform-specific operations for you.

Using the API

To initialize your application, you should first call ulCreateApp().

To create a window, call ulCreateWindow().

To create a web-page overlay within a window, call ulCreateOverlay().

Functions
ACExport ULSettings	ulCreateSettings ()
	Create settings with default values (see <AppCore/App.h>).

ACExport void	ulDestroySettings (ULSettings settings)
	Destroy settings.

ACExport void	ulSettingsSetDeveloperName (ULSettings settings, ULString name)
	Set the name of the developer of this app.

ACExport void	ulSettingsSetAppName (ULSettings settings, ULString name)
	Set the name of this app.

ACExport void	ulSettingsSetFileSystemPath (ULSettings settings, ULString path)
	Set the root file path for our file system, you should set this to the relative path where all of your app data is.

ACExport void	ulSettingsSetLoadShadersFromFileSystem (ULSettings settings, bool enabled)
	Set whether or not we should load and compile shaders from the file system (eg, from the /shaders/ path, relative to file_system_path).

ACExport void	ulSettingsSetForceCPURenderer (ULSettings settings, bool force_cpu)
	We try to use the GPU renderer when a compatible GPU is detected.

ACExport ULApp	ulCreateApp (ULSettings settings, ULConfig config)
	Create the App singleton.

ACExport void	ulDestroyApp (ULApp app)
	Destroy the App instance.

ACExport void	ulAppSetUpdateCallback (ULApp app, ULUpdateCallback callback, void *user_data)
	Set a callback for whenever the App updates.

ACExport bool	ulAppIsRunning (ULApp app)
	Whether or not the App is running.

ACExport ULMonitor	ulAppGetMainMonitor (ULApp app)
	Get the main monitor (this is never NULL).

ACExport ULRenderer	ulAppGetRenderer (ULApp app)
	Get the underlying Renderer instance.

ACExport void	ulAppRun (ULApp app)
	Run the main loop.

ACExport void	ulAppQuit (ULApp app)
	Quit the application.

ACExport double	ulMonitorGetScale (ULMonitor monitor)
	Get the monitor's DPI scale (1.0 = 100%).

ACExport unsigned int	ulMonitorGetWidth (ULMonitor monitor)
	Get the width of the monitor (in pixels).

ACExport unsigned int	ulMonitorGetHeight (ULMonitor monitor)
	Get the height of the monitor (in pixels).

ACExport ULWindow	ulCreateWindow (ULMonitor monitor, unsigned int width, unsigned int height, bool fullscreen, unsigned int window_flags)
	Create a new Window.

ACExport void	ulDestroyWindow (ULWindow window)
	Destroy a Window.

ACExport void	ulWindowSetCloseCallback (ULWindow window, ULCloseCallback callback, void *user_data)
	Set a callback to be notified when a window closes.

ACExport void	ulWindowSetResizeCallback (ULWindow window, ULResizeCallback callback, void *user_data)
	Set a callback to be notified when a window resizes (parameters are passed back in pixels).

ACExport unsigned int	ulWindowGetScreenWidth (ULWindow window)
	Get window width (in screen coordinates).

ACExport unsigned int	ulWindowGetWidth (ULWindow window)
	Get window width (in pixels).

ACExport unsigned int	ulWindowGetScreenHeight (ULWindow window)
	Get window height (in screen coordinates).

ACExport unsigned int	ulWindowGetHeight (ULWindow window)
	Get window height (in pixels).

ACExport void	ulWindowMoveTo (ULWindow window, int x, int y)
	Move the window to a new position (in screen coordinates) relative to the top-left of the monitor area.

ACExport void	ulWindowMoveToCenter (ULWindow)
	Move the window to the center of the monitor.

ACExport int	ulWindowGetPositionX (ULWindow window)
	Get the x-position of the window (in screen coordinates) relative to the top-left of the monitor area.

ACExport int	ulWindowGetPositionY (ULWindow window)
	Get the y-position of the window (in screen coordinates) relative to the top-left of the monitor area.

ACExport bool	ulWindowIsFullscreen (ULWindow window)
	Get whether or not a window is fullscreen.

ACExport double	ulWindowGetScale (ULWindow window)
	Get the DPI scale of a window.

ACExport void	ulWindowSetTitle (ULWindow window, const char *title)
	Set the window title.

ACExport void	ulWindowSetCursor (ULWindow window, ULCursor cursor)
	Set the cursor for a window.

ACExport void	ulWindowShow (ULWindow window)
	Show the window (if it was previously hidden).

ACExport void	ulWindowHide (ULWindow window)
	Hide the window.

ACExport bool	ulWindowIsVisible (ULWindow window)
	Whether or not the window is currently visible (not hidden).

ACExport void	ulWindowClose (ULWindow window)
	Close a window.

ACExport int	ulWindowScreenToPixels (ULWindow window, int val)
	Convert screen coordinates to pixels using the current DPI scale.

ACExport int	ulWindowPixelsToScreen (ULWindow window, int val)
	Convert pixels to screen coordinates using the current DPI scale.

ACExport void *	ulWindowGetNativeHandle (ULWindow window)
	Get the underlying native window handle.

ACExport ULOverlay	ulCreateOverlay (ULWindow window, unsigned int width, unsigned int height, int x, int y)
	Create a new Overlay.

ACExport ULOverlay	ulCreateOverlayWithView (ULWindow window, ULView view, int x, int y)
	Create a new Overlay, wrapping an existing View.

ACExport void	ulDestroyOverlay (ULOverlay overlay)
	Destroy an overlay.

ACExport ULView	ulOverlayGetView (ULOverlay overlay)
	Get the underlying View.

ACExport unsigned int	ulOverlayGetWidth (ULOverlay overlay)
	Get the width (in pixels).

ACExport unsigned int	ulOverlayGetHeight (ULOverlay overlay)
	Get the height (in pixels).

ACExport int	ulOverlayGetX (ULOverlay overlay)
	Get the x-position (offset from the left of the Window), in pixels.

ACExport int	ulOverlayGetY (ULOverlay overlay)
	Get the y-position (offset from the top of the Window), in pixels.

ACExport void	ulOverlayMoveTo (ULOverlay overlay, int x, int y)
	Move the overlay to a new position (in pixels).

ACExport void	ulOverlayResize (ULOverlay overlay, unsigned int width, unsigned int height)
	Resize the overlay (and underlying View), dimensions should be specified in pixels.

ACExport bool	ulOverlayIsHidden (ULOverlay overlay)
	Whether or not the overlay is hidden (not drawn).

ACExport void	ulOverlayHide (ULOverlay overlay)
	Hide the overlay (will no longer be drawn).

ACExport void	ulOverlayShow (ULOverlay overlay)
	Show the overlay.

ACExport bool	ulOverlayHasFocus (ULOverlay overlay)
	Whether or not an overlay has keyboard focus.

ACExport void	ulOverlayFocus (ULOverlay overlay)
	Grant this overlay exclusive keyboard focus.

ACExport void	ulOverlayUnfocus (ULOverlay overlay)
	Remove keyboard focus.

ACExport void	ulEnablePlatformFontLoader ()
	This is only needed if you are not calling ulCreateApp().

ACExport void	ulEnablePlatformFileSystem (ULString base_dir)
	This is only needed if you are not calling ulCreateApp().

ACExport void	ulEnableDefaultLogger (ULString log_path)
	This is only needed if you are not calling ulCreateApp().

Macros
#define	ACExport __attribute__((visibility("default")))

Typedefs
typedef struct C_Settings *	ULSettings

typedef struct C_App *	ULApp

typedef struct C_Window *	ULWindow

typedef struct C_Monitor *	ULMonitor

typedef struct C_Overlay *	ULOverlay

typedef void(*	ULUpdateCallback) (void *user_data)

typedef void(*	ULCloseCallback) (void *user_data, ULWindow window)

typedef void(*	ULResizeCallback) (void *user_data, ULWindow window, unsigned int width, unsigned int height)

Enumerations
enum	ULWindowFlags { kWindowFlags_Borderless = 1 << 0 , kWindowFlags_Titled = 1 << 1 , kWindowFlags_Resizable = 1 << 2 , kWindowFlags_Maximizable = 1 << 3 , kWindowFlags_Hidden = 1 << 4 }
	Window creation flags. More...

Function Documentation

◆ ulAppGetMainMonitor()

ACExport ULMonitor ulAppGetMainMonitor ( ULApp app )

Get the main monitor (this is never NULL).

Note: We'll add monitor enumeration later.

◆ ulAppGetRenderer()

ACExport ULRenderer ulAppGetRenderer ( ULApp app )

Get the underlying Renderer instance.

◆ ulAppIsRunning()

ACExport bool ulAppIsRunning ( ULApp app )

Whether or not the App is running.

◆ ulAppQuit()

ACExport void ulAppQuit ( ULApp app )

Quit the application.

◆ ulAppRun()

ACExport void ulAppRun ( ULApp app )

Run the main loop.

◆ ulAppSetUpdateCallback()

ACExport void ulAppSetUpdateCallback	(	ULApp	app,
		ULUpdateCallback	callback,
		void *	user_data
	)

Set a callback for whenever the App updates.

You should update all app logic here.

Note: This event is fired right before the run loop calls Renderer::Update and Renderer::Render.

◆ ulCreateApp()

ACExport ULApp ulCreateApp	(	ULSettings	settings,
		ULConfig	config
	)

Create the App singleton.

Parameters

settings	Settings to customize App runtime behavior. You can pass NULL for this parameter to use default settings.
config	Config options for the Ultralight renderer. You can pass NULL for this parameter to use default config.

Note: You should only create one of these per application lifetime.; Certain Config options may be overridden during App creation, most commonly Config::face_winding and Config::device_scale_hint.

◆ ulCreateOverlay()

ACExport ULOverlay ulCreateOverlay	(	ULWindow	window,
		unsigned int	width,
		unsigned int	height,
		int	x,
		int	y
	)

Create a new Overlay.

Parameters

window	The window to create the Overlay in.
width	The width in pixels.
height	The height in pixels.
x	The x-position (offset from the left of the Window), in pixels.
y	The y-position (offset from the top of the Window), in pixels.

Note: Each Overlay is essentially a View and an on-screen quad. You should create the Overlay then load content into the underlying View.

◆ ulCreateOverlayWithView()

ACExport ULOverlay ulCreateOverlayWithView	(	ULWindow	window,
		ULView	view,
		int	x,
		int	y
	)

Create a new Overlay, wrapping an existing View.

Parameters

window	The window to create the Overlay in. (we currently only support one window per application)
view	The View to wrap (will use its width and height).
x	The x-position (offset from the left of the Window), in pixels.
y	The y-position (offset from the top of the Window), in pixels.

Note: Each Overlay is essentially a View and an on-screen quad. You should create the Overlay then load content into the underlying View.

◆ ulCreateSettings()

ACExport ULSettings ulCreateSettings ( )

Create settings with default values (see <AppCore/App.h>).

◆ ulCreateWindow()

ACExport ULWindow ulCreateWindow	(	ULMonitor	monitor,
		unsigned int	width,
		unsigned int	height,
		bool	fullscreen,
		unsigned int	window_flags
	)

Create a new Window.

Parameters

monitor	The monitor to create the Window on.
width	The width (in screen coordinates).
height	The height (in screen coordinates).
fullscreen	Whether or not the window is fullscreen.
window_flags	Various window flags.

◆ ulDestroyApp()

ACExport void ulDestroyApp ( ULApp app )

Destroy the App instance.

◆ ulDestroyOverlay()

ACExport void ulDestroyOverlay ( ULOverlay overlay )

Destroy an overlay.

◆ ulDestroySettings()

ACExport void ulDestroySettings ( ULSettings settings )

Destroy settings.

◆ ulDestroyWindow()

ACExport void ulDestroyWindow ( ULWindow window )

Destroy a Window.

◆ ulEnableDefaultLogger()

ACExport void ulEnableDefaultLogger ( ULString log_path )

This is only needed if you are not calling ulCreateApp().

Initializes the default logger (writes the log to a file).

You should specify a writable log path to write the log to for example "./ultralight.log".

◆ ulEnablePlatformFileSystem()

ACExport void ulEnablePlatformFileSystem ( ULString base_dir )

This is only needed if you are not calling ulCreateApp().

Initializes the platform file system (needed for loading file:/// URLs) and sets it as the current FileSystem.

You can specify a base directory path to resolve relative paths against.

◆ ulEnablePlatformFontLoader()

ACExport void ulEnablePlatformFontLoader ( )

This is only needed if you are not calling ulCreateApp().

Initializes the platform font loader and sets it as the current FontLoader.

◆ ulMonitorGetHeight()

ACExport unsigned int ulMonitorGetHeight ( ULMonitor monitor )

Get the height of the monitor (in pixels).

◆ ulMonitorGetScale()

ACExport double ulMonitorGetScale ( ULMonitor monitor )

Get the monitor's DPI scale (1.0 = 100%).

◆ ulMonitorGetWidth()

ACExport unsigned int ulMonitorGetWidth ( ULMonitor monitor )

Get the width of the monitor (in pixels).

◆ ulOverlayFocus()

ACExport void ulOverlayFocus ( ULOverlay overlay )

Grant this overlay exclusive keyboard focus.

◆ ulOverlayGetHeight()

ACExport unsigned int ulOverlayGetHeight ( ULOverlay overlay )

Get the height (in pixels).

◆ ulOverlayGetView()

ACExport ULView ulOverlayGetView ( ULOverlay overlay )

Get the underlying View.

◆ ulOverlayGetWidth()

ACExport unsigned int ulOverlayGetWidth ( ULOverlay overlay )

Get the width (in pixels).

◆ ulOverlayGetX()

ACExport int ulOverlayGetX ( ULOverlay overlay )

Get the x-position (offset from the left of the Window), in pixels.

◆ ulOverlayGetY()

ACExport int ulOverlayGetY ( ULOverlay overlay )

Get the y-position (offset from the top of the Window), in pixels.

◆ ulOverlayHasFocus()

ACExport bool ulOverlayHasFocus ( ULOverlay overlay )

Whether or not an overlay has keyboard focus.

◆ ulOverlayHide()

ACExport void ulOverlayHide ( ULOverlay overlay )

Hide the overlay (will no longer be drawn).

◆ ulOverlayIsHidden()

ACExport bool ulOverlayIsHidden ( ULOverlay overlay )

Whether or not the overlay is hidden (not drawn).

◆ ulOverlayMoveTo()

ACExport void ulOverlayMoveTo	(	ULOverlay	overlay,
		int	x,
		int	y
	)

Move the overlay to a new position (in pixels).

◆ ulOverlayResize()

ACExport void ulOverlayResize	(	ULOverlay	overlay,
		unsigned int	width,
		unsigned int	height
	)

Resize the overlay (and underlying View), dimensions should be specified in pixels.

◆ ulOverlayShow()

ACExport void ulOverlayShow ( ULOverlay overlay )

Show the overlay.

◆ ulOverlayUnfocus()

ACExport void ulOverlayUnfocus ( ULOverlay overlay )

Remove keyboard focus.

◆ ulSettingsSetAppName()

ACExport void ulSettingsSetAppName	(	ULSettings	settings,
		ULString	name
	)

Set the name of this app.

This is used to generate a unique path to store local application data on the user's machine.

Default is "MyApp"

◆ ulSettingsSetDeveloperName()

ACExport void ulSettingsSetDeveloperName	(	ULSettings	settings,
		ULString	name
	)

Set the name of the developer of this app.

This is used to generate a unique path to store local application data on the user's machine.

Default is "MyCompany"

◆ ulSettingsSetFileSystemPath()

ACExport void ulSettingsSetFileSystemPath	(	ULSettings	settings,
		ULString	path
	)

Set the root file path for our file system, you should set this to the relative path where all of your app data is.

This will be used to resolve all file URLs, eg file:///page.html

Note

The default path is "./assets/"

   This relative path is resolved using the following logic:
    - Windows: relative to the executable path
    - Linux:   relative to the executable path
    - macOS:   relative to YourApp.app/Contents/Resources/

◆ ulSettingsSetForceCPURenderer()

ACExport void ulSettingsSetForceCPURenderer	(	ULSettings	settings,
		bool	force_cpu
	)

We try to use the GPU renderer when a compatible GPU is detected.

Set this to true to force the engine to always use the CPU renderer.

◆ ulSettingsSetLoadShadersFromFileSystem()

ACExport void ulSettingsSetLoadShadersFromFileSystem	(	ULSettings	settings,
		bool	enabled
	)

Set whether or not we should load and compile shaders from the file system (eg, from the /shaders/ path, relative to file_system_path).

If this is false (the default), we will instead load pre-compiled shaders from memory which speeds up application startup time.

◆ ulWindowClose()

ACExport void ulWindowClose ( ULWindow window )

Close a window.

◆ ulWindowGetHeight()

ACExport unsigned int ulWindowGetHeight ( ULWindow window )

Get window height (in pixels).

◆ ulWindowGetNativeHandle()

ACExport void * ulWindowGetNativeHandle ( ULWindow window )

Get the underlying native window handle.

Note

This is: - HWND on Windows

NSWindow* on macOS
GLFWwindow* on Linux

◆ ulWindowGetPositionX()

ACExport int ulWindowGetPositionX ( ULWindow window )

Get the x-position of the window (in screen coordinates) relative to the top-left of the monitor area.

◆ ulWindowGetPositionY()

ACExport int ulWindowGetPositionY ( ULWindow window )

Get the y-position of the window (in screen coordinates) relative to the top-left of the monitor area.

◆ ulWindowGetScale()

ACExport double ulWindowGetScale ( ULWindow window )

Get the DPI scale of a window.

◆ ulWindowGetScreenHeight()

ACExport unsigned int ulWindowGetScreenHeight ( ULWindow window )

Get window height (in screen coordinates).

◆ ulWindowGetScreenWidth()

ACExport unsigned int ulWindowGetScreenWidth ( ULWindow window )

Get window width (in screen coordinates).

◆ ulWindowGetWidth()

ACExport unsigned int ulWindowGetWidth ( ULWindow window )

Get window width (in pixels).

◆ ulWindowHide()

ACExport void ulWindowHide ( ULWindow window )

Hide the window.

◆ ulWindowIsFullscreen()

ACExport bool ulWindowIsFullscreen ( ULWindow window )

Get whether or not a window is fullscreen.

◆ ulWindowIsVisible()

ACExport bool ulWindowIsVisible ( ULWindow window )

Whether or not the window is currently visible (not hidden).

◆ ulWindowMoveTo()

ACExport void ulWindowMoveTo	(	ULWindow	window,
		int	x,
		int	y
	)

Move the window to a new position (in screen coordinates) relative to the top-left of the monitor area.

◆ ulWindowMoveToCenter()

ACExport void ulWindowMoveToCenter ( ULWindow )

Move the window to the center of the monitor.

◆ ulWindowPixelsToScreen()

ACExport int ulWindowPixelsToScreen	(	ULWindow	window,
		int	val
	)

Convert pixels to screen coordinates using the current DPI scale.

◆ ulWindowScreenToPixels()

ACExport int ulWindowScreenToPixels	(	ULWindow	window,
		int	val
	)

Convert screen coordinates to pixels using the current DPI scale.

◆ ulWindowSetCloseCallback()

ACExport void ulWindowSetCloseCallback	(	ULWindow	window,
		ULCloseCallback	callback,
		void *	user_data
	)

Set a callback to be notified when a window closes.

◆ ulWindowSetCursor()

ACExport void ulWindowSetCursor	(	ULWindow	window,
		ULCursor	cursor
	)

Set the cursor for a window.

◆ ulWindowSetResizeCallback()

ACExport void ulWindowSetResizeCallback	(	ULWindow	window,
		ULResizeCallback	callback,
		void *	user_data
	)

Set a callback to be notified when a window resizes (parameters are passed back in pixels).

◆ ulWindowSetTitle()

ACExport void ulWindowSetTitle	(	ULWindow	window,
		const char *	title
	)

Set the window title.

◆ ulWindowShow()

ACExport void ulWindowShow ( ULWindow window )

Show the window (if it was previously hidden).

Macro Definition Documentation

◆ ACExport

#define ACExport __attribute__((visibility("default")))

Typedef Documentation

◆ ULApp

typedef struct C_App* ULApp

◆ ULCloseCallback

typedef void(* ULCloseCallback) (void *user_data, ULWindow window)

◆ ULMonitor

typedef struct C_Monitor* ULMonitor

◆ ULOverlay

typedef struct C_Overlay* ULOverlay

◆ ULResizeCallback

typedef void(* ULResizeCallback) (void *user_data, ULWindow window, unsigned int width, unsigned int height)

◆ ULSettings

typedef struct C_Settings* ULSettings

◆ ULUpdateCallback

typedef void(* ULUpdateCallback) (void *user_data)

◆ ULWindow

typedef struct C_Window* ULWindow

Enumeration Type Documentation

◆ ULWindowFlags

enum ULWindowFlags

Window creation flags.

See also: Window::Create

Enumerator
kWindowFlags_Borderless
kWindowFlags_Titled
kWindowFlags_Resizable
kWindowFlags_Maximizable
kWindowFlags_Hidden

Details

Using the API

Functions

Macros

Typedefs

Enumerations

Function Documentation

◆ ulAppGetMainMonitor()

◆ ulAppGetRenderer()

◆ ulAppIsRunning()

◆ ulAppQuit()

◆ ulAppRun()

◆ ulAppSetUpdateCallback()

◆ ulCreateApp()

◆ ulCreateOverlay()

◆ ulCreateOverlayWithView()

◆ ulCreateSettings()

◆ ulCreateWindow()

◆ ulDestroyApp()

◆ ulDestroyOverlay()

◆ ulDestroySettings()

◆ ulDestroyWindow()

◆ ulEnableDefaultLogger()

◆ ulEnablePlatformFileSystem()

◆ ulEnablePlatformFontLoader()

◆ ulMonitorGetHeight()

◆ ulMonitorGetScale()

◆ ulMonitorGetWidth()

◆ ulOverlayFocus()

◆ ulOverlayGetHeight()

◆ ulOverlayGetView()

◆ ulOverlayGetWidth()

◆ ulOverlayGetX()

◆ ulOverlayGetY()

◆ ulOverlayHasFocus()

◆ ulOverlayHide()

◆ ulOverlayIsHidden()

◆ ulOverlayMoveTo()

◆ ulOverlayResize()

◆ ulOverlayShow()

◆ ulOverlayUnfocus()

◆ ulSettingsSetAppName()

◆ ulSettingsSetDeveloperName()

◆ ulSettingsSetFileSystemPath()

◆ ulSettingsSetForceCPURenderer()

◆ ulSettingsSetLoadShadersFromFileSystem()

◆ ulWindowClose()

◆ ulWindowGetHeight()

◆ ulWindowGetNativeHandle()

◆ ulWindowGetPositionX()

◆ ulWindowGetPositionY()

◆ ulWindowGetScale()

◆ ulWindowGetScreenHeight()

◆ ulWindowGetScreenWidth()

◆ ulWindowGetWidth()

◆ ulWindowHide()

◆ ulWindowIsFullscreen()

◆ ulWindowIsVisible()

◆ ulWindowMoveTo()

◆ ulWindowMoveToCenter()

◆ ulWindowPixelsToScreen()

◆ ulWindowScreenToPixels()

◆ ulWindowSetCloseCallback()

◆ ulWindowSetCursor()

◆ ulWindowSetResizeCallback()

◆ ulWindowSetTitle()

◆ ulWindowShow()

Macro Definition Documentation

◆ ACExport

Typedef Documentation

◆ ULApp

◆ ULCloseCallback

◆ ULMonitor

◆ ULOverlay

◆ ULResizeCallback

◆ ULSettings

◆ ULUpdateCallback

◆ ULWindow

Enumeration Type Documentation

◆ ULWindowFlags