Version: 21 Aug 2024

Graphics

The APIs for the graphics system. More...

Classes

	Name
struct	MLGraphicsOptions The graphics options provided for client creation.
struct	MLGraphicsFrameParamsEx The frame parameters requested for the next rendered frame.
struct	MLGraphicsClipExtentsInfo The static clip extents defined for all possible eye positions.
struct	MLGraphicsClipExtentsParams The clip extents parameters.
struct	MLGraphicsClipExtentsInfoArrayEx The clip extents array returned from MLGraphicsGetClipExtentsEx().
struct	MLGraphicsRenderTarget Definition of a single render target defined in MLGraphicsRenderBufferInfo.
struct	MLGraphicsRenderBufferInfo Definition of a single buffer entry for all virtual cameras as defined in MLGraphicsRenderTargetsInfo.
struct	MLGraphicsRenderTargetsInfo The complete definition of all possible buffered entries along with associated metadata.
struct	MLGraphicsVirtualCameraInfo The per virtual camera information as defined in #MLGraphicsVirtualCameraInfoArray.
struct	MLGraphicsFrameInfo Information about the current render frame populated by MLGraphicsBeginFrameEx(). This struct must be populated by calling MLGraphicsFrameInfoInit() before being used in a call to MLGraphicsBeginFrameEx().
struct	MLGraphicsClientPerformanceInfo Performance timing information for the graphics client.

Types

	Name
typedef struct MLGraphicsOptions	MLGraphicsOptions The graphics options provided for client creation.
typedef struct MLGraphicsFrameParamsEx	MLGraphicsFrameParamsEx The frame parameters requested for the next rendered frame.
typedef struct MLGraphicsClipExtentsInfo	MLGraphicsClipExtentsInfo The static clip extents defined for all possible eye positions.
typedef struct MLGraphicsClipExtentsParams	MLGraphicsClipExtentsParams The clip extents parameters.
typedef struct MLGraphicsClipExtentsInfoArrayEx	MLGraphicsClipExtentsInfoArrayEx The clip extents array returned from MLGraphicsGetClipExtentsEx().
typedef struct MLGraphicsRenderTarget	MLGraphicsRenderTarget Definition of a single render target defined in MLGraphicsRenderBufferInfo.
typedef struct MLGraphicsRenderBufferInfo	MLGraphicsRenderBufferInfo Definition of a single buffer entry for all virtual cameras as defined in MLGraphicsRenderTargetsInfo.
typedef struct MLGraphicsRenderTargetsInfo	MLGraphicsRenderTargetsInfo The complete definition of all possible buffered entries along with associated metadata.
typedef struct MLGraphicsVirtualCameraInfo	MLGraphicsVirtualCameraInfo The per virtual camera information as defined in #MLGraphicsVirtualCameraInfoArray.
typedef struct MLGraphicsFrameInfo	MLGraphicsFrameInfo Information about the current render frame populated by MLGraphicsBeginFrameEx(). This struct must be populated by calling MLGraphicsFrameInfoInit() before being used in a call to MLGraphicsBeginFrameEx().
typedef struct MLGraphicsClientPerformanceInfo	MLGraphicsClientPerformanceInfo Performance timing information for the graphics client.

Enums

	Name
enum	MLGraphicsFlags { MLGraphicsFlags_NoDepth = 1 << 0, MLGraphicsFlags_DebugMode = 1 << 2, MLGraphicsFlags_Headlock = 1 << 3, MLGraphicsFlags_Default = 0, MLGraphicsFlags_Ensure32Bits = 0x7FFFFFFF } The graphics flags used as part of client creation.
enum	MLSurfaceFormat { MLSurfaceFormat_Unknown = 0, MLSurfaceFormat_RGBA8UNorm, MLSurfaceFormat_RGBA8UNormSRGB, MLSurfaceFormat_RGB10A2UNorm, MLSurfaceFormat_RGBA16Float, MLSurfaceFormat_D32Float, MLSurfaceFormat_D24NormS8, MLSurfaceFormat_D32FloatS8, MLSurfaceFormat_Ensure32Bits = 0x7FFFFFFF } The definition of the supported color/depth surface formats.
enum	MLGraphicsVirtualCameraName { MLGraphicsVirtualCameraName_Combined = -1, MLGraphicsVirtualCameraName_Left = 0, MLGraphicsVirtualCameraName_Right, MLGraphicsVirtualCameraName_Count, MLGraphicsVirtualCameraName_Ensure32Bits = 0x7FFFFFFF } The metadata name associated with each virtual camera.
enum	Anonymous Enum 10 { MLGraphics_BufferCount = 3 }
enum	MLGraphicsProjectionType { MLGraphicsProjectionType_SignedZ = 0, MLGraphicsProjectionType_ReversedInfiniteZ = 1, MLGraphicsProjectionType_UnsignedZ = 2, MLGraphicsProjectionType_Ensure32Bits = 0x7FFFFFFF } Defines the requested projection matrix model for rendering.
enum	MLGraphicsEnvironmentBlendMode { MLGraphicsEnvironmentBlendMode_Additive = 0, MLGraphicsEnvironmentBlendMode_Alpha_Blend = 1, MLGraphicsEnvironmentBlendMode_Ensure32Bits = 0x7FFFFFFF } Defines how the final frame will be blended with environment.
enum	Anonymous Enum 11 { MLGraphicsBlobCache_DefaultMaxEntryBytes = 512 * 1024, MLGraphicsBlobCache_DefaultMaxTotalBytes = 8 * 1024 * 1024 }

Functions

	Name
void	MLGraphicsFrameParamsExInit(MLGraphicsFrameParamsEx * inout_frame_params) Initializes a MLGraphicsFrameParamsEx with the default parameters.
void	MLGraphicsClipExtentsParamsInit(MLGraphicsClipExtentsParams * inout_params) Initializes default values for MLGraphicsClipExtentsParams.
void	MLGraphicsClipExtentsInfoArrayExInit(MLGraphicsClipExtentsInfoArrayEx * inout_array) Initializes default values for MLGraphicsClipExtentsInfoArrayEx.
void	MLGraphicsFrameInfoInit(MLGraphicsFrameInfo * inout_frame_info) Initializes default values for MLGraphicsFrameInfo.
MLResult	MLGraphicsEnableBlobCacheGL(const char * filename, uint32_t max_entry_bytes, uint32_t max_total_bytes) Enable shader blob cache for OpenGL.
MLResult	MLGraphicsCreateClientGL(const MLGraphicsOptions options, MLHandle opengl_context, MLHandle out_graphics_client) Create the GL/GLES graphics client.
uint32_t	MLGraphicsGLFormatFromMLSurfaceFormat(MLSurfaceFormat format) Convert MLSurfaceFormat to OpenGL internal format.
MLSurfaceFormat	MLGraphicsMLSurfaceFormatFromGLFormat(uint32_t format) Convert OpenGL internal format to MLSurfaceFormat.
MLResult	MLGraphicsCreateClientVk(const MLGraphicsOptions options, const VkInstance vulkan_instance, const VkPhysicalDevice vulkan_physical_device, const VkDevice vulkan_logical_device, MLHandle out_graphics_client) Create the VK graphics client.
VkFormat	MLGraphicsVkFormatFromMLSurfaceFormat(const MLSurfaceFormat format) Convert MLSurfaceFormat to VkFormat.
MLSurfaceFormat	MLGraphicsMLSurfaceFormatFromVkFormat(const VkFormat format) Convert VkFormat to MLSurfaceFormat.
MLResult	MLGraphicsDestroyClient(MLHandle * inout_graphics_client) Destroy a GL/GLES or VK client.
MLResult	MLGraphicsBeginFrameEx(MLHandle graphics_client, const MLGraphicsFrameParamsEx params, MLGraphicsFrameInfo out_frame_info) Request to begin rendering a new frame in the graphics system.
MLResult	MLGraphicsSignalSyncObjectGL(MLHandle graphics_client, MLHandle sync_object) Signal the sync object provided for each virtual camera for GL/GLES clients.
MLResult	MLGraphicsGetClipExtentsEx(MLHandle graphics_client, const MLGraphicsClipExtentsParams params, MLGraphicsClipExtentsInfoArrayEx out_array) Get the conservative clip extents information for each virtual camera.
MLResult	MLGraphicsGetRenderTargets(MLHandle graphics_client, MLGraphicsRenderTargetsInfo * out_targets) Get a list of all buffered entries.
MLResult	MLGraphicsEndFrame(MLHandle graphics_client, MLHandle handle) Submit a completed frame to the graphics system.
MLResult	MLGraphicsGetClientPerformanceInfo(MLHandle graphics_client, MLGraphicsClientPerformanceInfo * out_info) Obtain latest performance metrics for the client.

Detailed Description

The APIs for the graphics system.

The enclosed APIs allow for interaction with the graphics system. In general, to integrate with the graphics system you will do so with a graphics client handle. There are two types of clients currently supported, a GL/GLES client supporting all GL/GLES APIs from 3.0 to 4.5, and a VK client which supports the latest VK definition on the platform. Once created, the client handle can be used to start/end frames, set the requested timing characteristics for the client, and query useful information about the client.

All timing, alignment, etc. of the CPU domain of the client with the asynchronous composition is also handled automatically by the API through the blocking behavior in MLGraphicsBeginFrameEx.

Note : In the current definition of the API, perception must have already been started prior to interacting with the graphics system and the perception lifetime is managed separate of the graphics system.

Warning

THIS API IS DEPRECATED IN FAVOR OF OPENXR APIs: https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html

Shared Object:

graphics.magicleap*

Enums Documentation

MLGraphicsFlags

Enumerator	Value	Description
MLGraphicsFlags_NoDepth	1 << 0	The client will not provide a depth buffer to the graphics system as part of rendering. Therefore the handle returned for all depth related resources from the graphics APIs will be invalid.
MLGraphicsFlags_DebugMode	1 << 2	Create a debug client with a debug configuration that provides extended logcat error logging. Useful to debug failures in API calls to the graphics system.
MLGraphicsFlags_Headlock	1 << 3	The client will lock all the content to the user's head pose. When enabled all of the content rendered by the app and system notifications will be in head locked mode. Use this mode with caution.
MLGraphicsFlags_Default	0	When #graphics_flags is set to default, the client configuration returned is the default configuration (color/depth, origin lower left, non-debug, no headlock).
MLGraphicsFlags_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The graphics flags used as part of client creation.

The flags are used to define the #graphics_flags member of the MLGraphicsOptions as part of the definition to create the client.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLSurfaceFormat

Enumerator	Value	Description
MLSurfaceFormat_Unknown	0	Invalid format for color/depth.
MLSurfaceFormat_RGBA8UNorm		32bit linear color format (RGBA8).
MLSurfaceFormat_RGBA8UNormSRGB		Gamma 2.2 32bit sRGB color format (RGBA8). Clients requesting this format are required to encode the final color into this surface as defined by the IEC 61966-2-1 specification.
MLSurfaceFormat_RGB10A2UNorm		32bit linear color format (R10G10B10A2).
MLSurfaceFormat_RGBA16Float		64bit linear color format (R16G16B16A16).
MLSurfaceFormat_D32Float		32bit floating point depth buffer (D32F).
MLSurfaceFormat_D24NormS8		24bit linear depth format with 8bit stencil (D24S8).
MLSurfaceFormat_D32FloatS8		32bit floating point depth format with 8bit stencil (D32FS8).
MLSurfaceFormat_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The definition of the supported color/depth surface formats.

Formats that can be specified for the color_format and depth_format in MLGraphicsOptions. For the best quality the recommended color format is MLSurfaceFormat_RGBA8UNormSRGB, and for depth (when defined) either MLSurfaceFormat_D32Float or MLSurfaceFormat_D32FloatS8.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsVirtualCameraName

Enumerator	Value	Description
MLGraphicsVirtualCameraName_Combined	-1	Name of the combined camera, the union of all virtual cameras.
MLGraphicsVirtualCameraName_Left	0	Name of virtual camera for left display.
MLGraphicsVirtualCameraName_Right		Name of virtual camera for right display.
MLGraphicsVirtualCameraName_Count		The maximum number of render virtual cameras.
MLGraphicsVirtualCameraName_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The metadata name associated with each virtual camera.

APIs within the graphics system will return information specific to a single virtual camera or both. The metadata name informs the client how to correlate the outputs of the API to a specific camera or both cameras.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Anonymous Enum 10

Enumerator	Value	Description
MLGraphics_BufferCount	3	The number of buffered entries for each virtual camera.

Definitions for Graphics system maximums.

MLGraphicsProjectionType

Enumerator	Value	Description
MLGraphicsProjectionType_SignedZ	0	Projection model with signed Z.
MLGraphicsProjectionType_ReversedInfiniteZ	1	Projection model reversed infinite Z.
MLGraphicsProjectionType_UnsignedZ	2	Projection model with unsigned Z.
MLGraphicsProjectionType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Defines the requested projection matrix model for rendering.

Provided as part of the MLGraphicsFrameParamsEx, defines the requested projection model for the intrinsic definition returned for each virtual camera from MLGraphicsBeginFrameEx.

The signed Z projection model is optimized for OpenGL use and transforms points into a left-hand, right-up-forward, Z range -1 (near) to 1 (far) projected coordinate space.

The reverse infinite Z projection model maps the Z range from 1 (near) to 0 (infinity).

Vulkan clients should use the unsigned Z projection model to ensure that NDC points end up in Z range 0 (near) to 1 (far).

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsEnvironmentBlendMode

Enumerator	Value	Description
MLGraphicsEnvironmentBlendMode_Additive	0	Ignore frame alpha and prohibit generation of segmented dimmer.
MLGraphicsEnvironmentBlendMode_Alpha_Blend	1	Use the resulting alpha after compostion potentially generating dimmer.
MLGraphicsEnvironmentBlendMode_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Defines how the final frame will be blended with environment.

For now only used for controlling the segmented dimmer behavior.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Anonymous Enum 11

Enumerator	Value	Description
MLGraphicsBlobCache_DefaultMaxEntryBytes	512 * 1024
MLGraphicsBlobCache_DefaultMaxTotalBytes	8 * 1024 * 1024

Default values suitable for use with MLGraphicsEnableBlobCacheGL().

Types Documentation

MLGraphicsOptions

typedef struct MLGraphicsOptions MLGraphicsOptions;

The graphics options provided for client creation.

MLGraphicsOptions defines the requested client configuration for creating GL/GLES or VK clients.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsFrameParamsEx

typedef struct MLGraphicsFrameParamsEx MLGraphicsFrameParamsEx;

The frame parameters requested for the next rendered frame.

The parameters defined by MLGraphicsFrameParamsEx are supplied to MLGraphicsBeginFrameEx from the client to define the requested characteristics of the next rendered frame.

This structure must be initialized by calling MLGraphicsFrameParamsExInit() before use.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsClipExtentsInfo

typedef struct MLGraphicsClipExtentsInfo MLGraphicsClipExtentsInfo;

The static clip extents defined for all possible eye positions.

Defines the conservative clip extents for the camera name that can be used for early update frustum culling in the client update path (prior to calling MLGraphicsBeginFrameEx).

Note: The client will need to obtain a headpose to combine with the provided matrices (transform and projection) to define the frustum. The general definition for camera from world (for the specified camera name) is MATprojection inv(MATtransform) inv(MATheadpose) for RHS multiplication.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsClipExtentsParams

typedef struct MLGraphicsClipExtentsParams MLGraphicsClipExtentsParams;

The clip extents parameters.

The parameters defined by MLGraphicsClipExtentsParams are supplied to MLGraphicsGetClipExtentsEx() from the client to define the requested characteristics of the clip extents.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsClipExtentsInfoArrayEx

typedef struct MLGraphicsClipExtentsInfoArrayEx MLGraphicsClipExtentsInfoArrayEx;

The clip extents array returned from MLGraphicsGetClipExtentsEx().

The clip extents array provides the conservative clip extents per metadata camera as defined by MLGraphicsClipExtentsInfo.

This structure must be initialized by calling MLGraphicsClipExtentsInfoArrayExInit() before use.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsRenderTarget

typedef struct MLGraphicsRenderTarget MLGraphicsRenderTarget;

Definition of a single render target defined in MLGraphicsRenderBufferInfo.

Each render target defines one of the buffered entries color/depth surfaces (with maximum count defined by MLGraphics_BufferCount). Clients can assume that the handle provided here will be in the list of handles returned from MLGraphicsBeginFrameEx.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsRenderBufferInfo

typedef struct MLGraphicsRenderBufferInfo MLGraphicsRenderBufferInfo;

Definition of a single buffer entry for all virtual cameras as defined in MLGraphicsRenderTargetsInfo.

Each buffer entry can contain a color / depth target and the target is valid if the handle != 0.

Note : When the client specifies the MLGraphicsFlags_NoDepth flag as part of client creation the depth targets will always be 0.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsRenderTargetsInfo

typedef struct MLGraphicsRenderTargetsInfo MLGraphicsRenderTargetsInfo;

The complete definition of all possible buffered entries along with associated metadata.

Statically defined after successfully creating the client, the MLGraphicsRenderTargetsInfo provides the definition of all of the buffered entries along with the global metadata. The client can assume that once queried the definition will not change and therefore does not need to be queried more than once at runtime.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsVirtualCameraInfo

typedef struct MLGraphicsVirtualCameraInfo MLGraphicsVirtualCameraInfo;

The per virtual camera information as defined in #MLGraphicsVirtualCameraInfoArray.

For each virtual camera the client is provided the exact definition of the camera properties along with the matrices needed to construct the full transform chain. In general the transform chain for each virtual camera is defined as MATprojection * inv(MATtransform) for RHS multiplication.

Note: The projection model is asymmetric and clients should not assume any of the symmetric properties of projection. Additionally both the transform and projection will change per frame and cannot be assumed to be static.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsFrameInfo

typedef struct MLGraphicsFrameInfo MLGraphicsFrameInfo;

Information about the current render frame populated by MLGraphicsBeginFrameEx(). This struct must be populated by calling MLGraphicsFrameInfoInit() before being used in a call to MLGraphicsBeginFrameEx().

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsClientPerformanceInfo

typedef struct MLGraphicsClientPerformanceInfo MLGraphicsClientPerformanceInfo;

Performance timing information for the graphics client.

Populated by MLGraphicsGetClientPerformanceInfo, the performance information contains all metrics tracked by the graphics system for the specified client. Metrics are calculated using a sliding window and can be used to adjust the client workload characteristics (i.e. scale, fidelity, etc).

Note: The internal metrics are also provided, informing the client of both the CPU and GPU cost of the internal operations of the graphics system (in the client process).

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Functions Documentation

MLGraphicsFrameParamsExInit

static inline void MLGraphicsFrameParamsExInit(
    MLGraphicsFrameParamsEx * inout_frame_params
)

Initializes a MLGraphicsFrameParamsEx with the default parameters.

Parameters


MLGraphicsFrameParamsEx *	inout_frame_params	The object to initialize with default settings.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsClipExtentsParamsInit

static inline void MLGraphicsClipExtentsParamsInit(
    MLGraphicsClipExtentsParams * inout_params
)

Initializes default values for MLGraphicsClipExtentsParams.

Parameters


MLGraphicsClipExtentsParams *	inout_params	The object to initialize with default settings.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsClipExtentsInfoArrayExInit

static inline void MLGraphicsClipExtentsInfoArrayExInit(
    MLGraphicsClipExtentsInfoArrayEx * inout_array
)

Initializes default values for MLGraphicsClipExtentsInfoArrayEx.

Parameters


MLGraphicsClipExtentsInfoArrayEx *	inout_array	The object to initialize with default settings.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsFrameInfoInit

static inline void MLGraphicsFrameInfoInit(
    MLGraphicsFrameInfo * inout_frame_info
)

Initializes default values for MLGraphicsFrameInfo.

Parameters


MLGraphicsFrameInfo *	inout_frame_info	The object to initialize with default settings.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsEnableBlobCacheGL

MLResult MLGraphicsEnableBlobCacheGL(
    const char * filename,
    uint32_t max_entry_bytes,
    uint32_t max_total_bytes
)

Enable shader blob cache for OpenGL.

Parameters


const char *	filename	Absolute path to a file to use for caching. Location must be writeable by application.
uint32_t	max_entry_bytes	Reserved for future use. Maximum size for a single blob entry. Currently defaults to 512KB.
uint32_t	max_total_bytes	Reserved for future use. Maximum total file size for the blob. Currently defaults to 8MB.

Returns


MLResult	MLResult_InvalidParam	Failed to enable blob cache due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully enabled blob cache.

Required Permissions:

None

OpenGL can cache & reuse shaders and other driver artifacts using a blob cache, speeding up loading & processing of shaders significantly on subseqent occurrences. This behavior persists across runs of the app as well, speeding up load times. This function is used to enable the blob caching using the specified file. The file path must be writeable by the application. The file will be created if it doesn't already exist.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsCreateClientGL

MLResult MLGraphicsCreateClientGL(
    const MLGraphicsOptions * options,
    MLHandle opengl_context,
    MLHandle * out_graphics_client
)

Create the GL/GLES graphics client.

Parameters


const MLGraphicsOptions *	options	The graphics options for resource creation.
MLHandle	opengl_context	The OpenGL context to use for resource creation.
MLHandle *	out_graphics_client	The handle to the created graphics client. Only valid if result is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to create graphics client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created graphics client.
MLResult	MLResult_UnspecifiedFailure	Failed to create graphics client due to an unknown error.

Required Permissions:

None

Create a graphics client for use with GL/GLES APIs using the provided options and specified opengl context. It is required that the opengl context specified here is only bound on the thread used to render the client frame and is the same context used to render the frame using the provided information from MLGraphicsBeginFrameEx.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsGLFormatFromMLSurfaceFormat

uint32_t MLGraphicsGLFormatFromMLSurfaceFormat(
    MLSurfaceFormat format
)

Convert MLSurfaceFormat to OpenGL internal format.

Parameters


MLSurfaceFormat	format	The MLSurfaceFormat to convert.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Return: The returned internal format.

MLGraphicsMLSurfaceFormatFromGLFormat

MLSurfaceFormat MLGraphicsMLSurfaceFormatFromGLFormat(
    uint32_t format
)

Convert OpenGL internal format to MLSurfaceFormat.

Parameters


uint32_t	format	The internal format to convert.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Return: The returned MLSurfaceFormat.

MLGraphicsCreateClientVk

MLResult MLGraphicsCreateClientVk(
    const MLGraphicsOptions * options,
    const VkInstance vulkan_instance,
    const VkPhysicalDevice vulkan_physical_device,
    const VkDevice vulkan_logical_device,
    MLHandle * out_graphics_client
)

Create the VK graphics client.

Parameters


const MLGraphicsOptions *	options	The graphics options for resource creation.
const VkInstance	vulkan_instance	The Vulkan instance used to create the physical and logical device.
const VkPhysicalDevice	vulkan_physical_device	The Vulkan physical device used to create the specified logical device.
const VkDevice	vulkan_logical_device	The Vulkan logical device to use for resource creation.
MLHandle *	out_graphics_client	The handle to the created graphics client. Only valid if result is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to create client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created client.
MLResult	MLResult_UnspecifiedFailure	Failed to create client due to an unknown error.

Required Permissions:

None

Create a graphics client for use with VK API using the provided options and specified physical and logical device. The color and depth surfaces are created internally, then exported to the application context. The initial layout of these surfaces is VK_IMAGE_LAYOUT_UNDEFINED. It is the application's responsibility to perform a layout transition of the surfaces before usage.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsVkFormatFromMLSurfaceFormat

VkFormat MLGraphicsVkFormatFromMLSurfaceFormat(
    const MLSurfaceFormat format
)

Convert MLSurfaceFormat to VkFormat.

Parameters


const MLSurfaceFormat	format	The MLSurfaceFormat to convert.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Return: The returned VkFormat.

MLGraphicsMLSurfaceFormatFromVkFormat

MLSurfaceFormat MLGraphicsMLSurfaceFormatFromVkFormat(
    const VkFormat format
)

Convert VkFormat to MLSurfaceFormat.

Parameters


const VkFormat	format	The VkFormat to convert.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Return: The returned MLSurfaceFormat.

MLGraphicsDestroyClient

MLResult MLGraphicsDestroyClient(
    MLHandle * inout_graphics_client
)

Destroy a GL/GLES or VK client.

Parameters


MLHandle *	inout_graphics_client	The graphics client to destroy.

Returns


MLResult	MLResult_InvalidParam	Failed to destroy client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully destroyed client.
MLResult	MLResult_UnspecifiedFailure	Failed to destroy client due to an unknown error.

Required Permissions:

None

Destroying the client will invalidate all resources associated with the client handle and invalidate the provided handle.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsBeginFrameEx

MLResult MLGraphicsBeginFrameEx(
    MLHandle graphics_client,
    const MLGraphicsFrameParamsEx * params,
    MLGraphicsFrameInfo * out_frame_info
)

Request to begin rendering a new frame in the graphics system.

Parameters


MLHandle	graphics_client	The graphics client to query.
const MLGraphicsFrameParamsEx *	params	The frame parameters for the frame.
MLGraphicsFrameInfo *	out_frame_info	Information returned for use when rendering the frame. Only valid if result is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to start frame due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully started frame.
MLResult	MLResult_Timeout	Failed to start frame due to blocking timeout limit being reached.
MLResult	MLResult_UnspecifiedFailure	Failed to start frame due to an unknown error.

Required Permissions:

None

Called to request the start of a new render frame and should be called as close as possible to the start of rendering to minimize the motion to photon latency. Only one frame can be rendered at a time and must be submitted by providing the returned handle to MLGraphicsEndFrame prior to another call to MLGraphicsBeginFrameEx. The call to begin/end frame should be made on the render thread alone of the client. It is required that a successful call to MLGraphicsFrameInfoInit be made before calling MLGraphicsBeginFrameEx. Faiure to call MLGraphicsFrameInfoInit before calling MLGraphicsBeginFrameEx will return a result of MLResult_NotImplemented.

Note : Calls to MLGraphicsBeginFrameEx can and will block the calling process. There are several reasons that lead to a block, including, the client is executing faster than the defined timing requested (and the block re-aligns the client timing), the client is not yet visible in the system, and the compositor has not yet moved to the next buffered entry (i.e. wraparound cases from fast client rendering). The call to MLGraphicsBeginFrameEx will timeout the block and return when the conditions to unblock have not been satisfied for the internal timeout period. The most common occurrence of the timeout is when the application is not currently visible.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLGraphicsSignalSyncObjectGL

MLResult MLGraphicsSignalSyncObjectGL(
    MLHandle graphics_client,
    MLHandle sync_object
)

Signal the sync object provided for each virtual camera for GL/GLES clients.

Parameters


MLHandle	graphics_client	The graphics client owning the sync object.
MLHandle	sync_object	The sync object to be signaled.

Returns


MLResult	MLResult_InvalidParam	Failed to signal object due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully signaled object.
MLResult	MLResult_UnspecifiedFailure	Failed to signal object due to an unknown error.

Required Permissions:

None

Required for each frame, after rendering each virtual camera (or multiple if stereo rendering) to signal the sync object in order to inform the graphics system that the rendering for the camera(s) has completed. All sync objects can be signaled after rendering all cameras, but results in lower fidelity in the graphics system.

Note: Vulkan clients are required to cast the sync object to VkSemaphore and add it to the signal semaphore list when submitting the last command buffer for the virtual camera(s).

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsGetClipExtentsEx

MLResult MLGraphicsGetClipExtentsEx(
    MLHandle graphics_client,
    const MLGraphicsClipExtentsParams * params,
    MLGraphicsClipExtentsInfoArrayEx * out_array
)

Get the conservative clip extents information for each virtual camera.

Parameters


MLHandle	graphics_client	The graphics client to query.
const MLGraphicsClipExtentsParams *	params	The clip extents parameters.
MLGraphicsClipExtentsInfoArrayEx *	out_array	The clip extents info array with all information required for update of each virtual camera. Only valid if result is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain extents due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully obtained extents.
MLResult	MLResult_UnspecifiedFailure	Failed to obtain extents due to an unknown error.

Required Permissions:

None

Clients should call this function once a frame to get the most accurate clip extents.

Attention

EXPERIMENTAL.

API Level:

MLGraphicsGetRenderTargets

MLResult MLGraphicsGetRenderTargets(
    MLHandle graphics_client,
    MLGraphicsRenderTargetsInfo * out_targets
)

Get a list of all buffered entries.

Parameters


MLHandle	graphics_client	The graphics client to query.
MLGraphicsRenderTargetsInfo *	out_targets	The render target info array. Only valid if result is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain target due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully obtained handle.
MLResult	MLResult_UnspecifiedFailure	Failed to obtain handle due to an unknown error.

Required Permissions:

None

Called after client initialization to obtain the definition of all buffered entries along with the associated metadata. Like #MLGraphicsGetClipExtents can be assumed that the output is unchanging for the lifetime of the client.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsEndFrame

MLResult MLGraphicsEndFrame(
    MLHandle graphics_client,
    MLHandle handle
)

Submit a completed frame to the graphics system.

Parameters


MLHandle	graphics_client	The graphics client to update.
MLHandle	handle	The handle provided from the call to MLGraphicsBeginFrameEx.

Returns


MLResult	MLResult_InvalidParam	Failed to end frame due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully ended frame.
MLResult	MLResult_UnspecifiedFailure	Failed to end frame due to an unknown error.

Required Permissions:

None

Submit a completed frame to the graphics system using the handle provided from MLGraphicsBeginFrameEx. Prior to submiting the frame the client must signal the sync objects provided by MLGraphicsBeginFrameEx, for GL/GLES clients with MLGraphicsSignalSyncObjectGL or for VK clients including that sync object as part of the signal semaphore list. For VK clients, the color and depth surfaces can be in any image layout when calling MLGraphicsEndFrame.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

MLGraphicsGetClientPerformanceInfo

MLResult MLGraphicsGetClientPerformanceInfo(
    MLHandle graphics_client,
    MLGraphicsClientPerformanceInfo * out_info
)

Obtain latest performance metrics for the client.

Parameters


MLHandle	graphics_client	The graphics client in which to query the performance.
MLGraphicsClientPerformanceInfo *	out_info	Current performance information for the client. Only valid if result is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to obtain client performance metrics due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully obtained client performance metrics.
MLResult	MLResult_UnspecifiedFailure	Failed to obtain client performance metrics due to an unknown error.

Required Permissions:

None

Can be called any time after the client has begun rendering frames to obtain the internally tracked performance metrics for the client and graphics system. Updated internally once per completed frame.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

Graphics

Classes​

Types​

Enums​

Functions​

Detailed Description​

Enums Documentation​

MLGraphicsFlags​

MLSurfaceFormat​

MLGraphicsVirtualCameraName​

Anonymous Enum 10​

MLGraphicsProjectionType​

MLGraphicsEnvironmentBlendMode​

Anonymous Enum 11​

Types Documentation​

MLGraphicsOptions​

MLGraphicsFrameParamsEx​

MLGraphicsClipExtentsInfo​

MLGraphicsClipExtentsParams​

MLGraphicsClipExtentsInfoArrayEx​

MLGraphicsRenderTarget​

MLGraphicsRenderBufferInfo​

MLGraphicsRenderTargetsInfo​

MLGraphicsVirtualCameraInfo​

MLGraphicsFrameInfo​

MLGraphicsClientPerformanceInfo​

Functions Documentation​

MLGraphicsFrameParamsExInit​

MLGraphicsClipExtentsParamsInit​

MLGraphicsClipExtentsInfoArrayExInit​

MLGraphicsFrameInfoInit​

MLGraphicsEnableBlobCacheGL​

MLGraphicsCreateClientGL​

MLGraphicsGLFormatFromMLSurfaceFormat​

MLGraphicsMLSurfaceFormatFromGLFormat​

MLGraphicsCreateClientVk​

MLGraphicsVkFormatFromMLSurfaceFormat​

MLGraphicsMLSurfaceFormatFromVkFormat​

MLGraphicsDestroyClient​

MLGraphicsBeginFrameEx​

MLGraphicsSignalSyncObjectGL​

MLGraphicsGetClipExtentsEx​

MLGraphicsGetRenderTargets​

MLGraphicsEndFrame​

MLGraphicsGetClientPerformanceInfo​

Classes

Types

Enums

Functions

Detailed Description

Enums Documentation

MLGraphicsFlags

MLSurfaceFormat

MLGraphicsVirtualCameraName

Anonymous Enum 10

MLGraphicsProjectionType

MLGraphicsEnvironmentBlendMode

Anonymous Enum 11

Types Documentation

MLGraphicsOptions

MLGraphicsFrameParamsEx

MLGraphicsClipExtentsInfo

MLGraphicsClipExtentsParams

MLGraphicsClipExtentsInfoArrayEx

MLGraphicsRenderTarget

MLGraphicsRenderBufferInfo

MLGraphicsRenderTargetsInfo

MLGraphicsVirtualCameraInfo

MLGraphicsFrameInfo

MLGraphicsClientPerformanceInfo

Functions Documentation

MLGraphicsFrameParamsExInit

MLGraphicsClipExtentsParamsInit

MLGraphicsClipExtentsInfoArrayExInit

MLGraphicsFrameInfoInit

MLGraphicsEnableBlobCacheGL

MLGraphicsCreateClientGL

MLGraphicsGLFormatFromMLSurfaceFormat

MLGraphicsMLSurfaceFormatFromGLFormat

MLGraphicsCreateClientVk

MLGraphicsVkFormatFromMLSurfaceFormat

MLGraphicsMLSurfaceFormatFromVkFormat

MLGraphicsDestroyClient

MLGraphicsBeginFrameEx

MLGraphicsSignalSyncObjectGL

MLGraphicsGetClipExtentsEx

MLGraphicsGetRenderTargets

MLGraphicsEndFrame

MLGraphicsGetClientPerformanceInfo