Skip to main content
Version: 21 Aug 2024

ml_graphics.h

Classes

Name
structMLGraphicsOptions
The graphics options provided for client creation.
structMLGraphicsFrameParamsEx
The frame parameters requested for the next rendered frame.
structMLGraphicsClipExtentsInfo
The static clip extents defined for all possible eye positions.
structMLGraphicsClipExtentsParams
The clip extents parameters.
structMLGraphicsClipExtentsInfoArrayEx
The clip extents array returned from MLGraphicsGetClipExtentsEx().
structMLGraphicsRenderTarget
Definition of a single render target defined in MLGraphicsRenderBufferInfo.
structMLGraphicsRenderBufferInfo
Definition of a single buffer entry for all virtual cameras as defined in MLGraphicsRenderTargetsInfo.
structMLGraphicsRenderTargetsInfo
The complete definition of all possible buffered entries along with associated metadata.
structMLGraphicsVirtualCameraInfo
The per virtual camera information as defined in #MLGraphicsVirtualCameraInfoArray.
structMLGraphicsFrameInfo
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().
structMLGraphicsClientPerformanceInfo
Performance timing information for the graphics client.

Types

Name
typedef struct MLGraphicsOptionsMLGraphicsOptions
The graphics options provided for client creation.
typedef struct MLGraphicsFrameParamsExMLGraphicsFrameParamsEx
The frame parameters requested for the next rendered frame.
typedef struct MLGraphicsClipExtentsInfoMLGraphicsClipExtentsInfo
The static clip extents defined for all possible eye positions.
typedef struct MLGraphicsClipExtentsParamsMLGraphicsClipExtentsParams
The clip extents parameters.
typedef struct MLGraphicsClipExtentsInfoArrayExMLGraphicsClipExtentsInfoArrayEx
The clip extents array returned from MLGraphicsGetClipExtentsEx().
typedef struct MLGraphicsRenderTargetMLGraphicsRenderTarget
Definition of a single render target defined in MLGraphicsRenderBufferInfo.
typedef struct MLGraphicsRenderBufferInfoMLGraphicsRenderBufferInfo
Definition of a single buffer entry for all virtual cameras as defined in MLGraphicsRenderTargetsInfo.
typedef struct MLGraphicsRenderTargetsInfoMLGraphicsRenderTargetsInfo
The complete definition of all possible buffered entries along with associated metadata.
typedef struct MLGraphicsVirtualCameraInfoMLGraphicsVirtualCameraInfo
The per virtual camera information as defined in #MLGraphicsVirtualCameraInfoArray.
typedef struct MLGraphicsFrameInfoMLGraphicsFrameInfo
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 MLGraphicsClientPerformanceInfoMLGraphicsClientPerformanceInfo
Performance timing information for the graphics client.

Enums

Name
enumMLGraphicsFlags
{
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.
enumMLSurfaceFormat
{
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.
enumMLGraphicsVirtualCameraName
{
MLGraphicsVirtualCameraName_Combined = -1,
MLGraphicsVirtualCameraName_Left = 0,
MLGraphicsVirtualCameraName_Right,
MLGraphicsVirtualCameraName_Count,
MLGraphicsVirtualCameraName_Ensure32Bits = 0x7FFFFFFF
}
The metadata name associated with each virtual camera.
enumAnonymous Enum 10
{
MLGraphics_BufferCount = 3
}
enumMLGraphicsProjectionType
{
MLGraphicsProjectionType_SignedZ = 0,
MLGraphicsProjectionType_ReversedInfiniteZ = 1,
MLGraphicsProjectionType_UnsignedZ = 2,
MLGraphicsProjectionType_Ensure32Bits = 0x7FFFFFFF
}
Defines the requested projection matrix model for rendering.
enumMLGraphicsEnvironmentBlendMode
{
MLGraphicsEnvironmentBlendMode_Additive = 0,
MLGraphicsEnvironmentBlendMode_Alpha_Blend = 1,
MLGraphicsEnvironmentBlendMode_Ensure32Bits = 0x7FFFFFFF
}
Defines how the final frame will be blended with environment.
enumAnonymous Enum 11
{
MLGraphicsBlobCache_DefaultMaxEntryBytes = 512 * 1024,
MLGraphicsBlobCache_DefaultMaxTotalBytes = 8 * 1024 * 1024
}

Functions

Name
voidMLGraphicsFrameParamsExInit(MLGraphicsFrameParamsEx * inout_frame_params)
Initializes a MLGraphicsFrameParamsEx with the default parameters.
voidMLGraphicsClipExtentsParamsInit(MLGraphicsClipExtentsParams * inout_params)
Initializes default values for MLGraphicsClipExtentsParams.
voidMLGraphicsClipExtentsInfoArrayExInit(MLGraphicsClipExtentsInfoArrayEx * inout_array)
Initializes default values for MLGraphicsClipExtentsInfoArrayEx.
voidMLGraphicsFrameInfoInit(MLGraphicsFrameInfo * inout_frame_info)
Initializes default values for MLGraphicsFrameInfo.
MLResultMLGraphicsEnableBlobCacheGL(const char * filename, uint32_t max_entry_bytes, uint32_t max_total_bytes)
Enable shader blob cache for OpenGL.
MLResultMLGraphicsCreateClientGL(const MLGraphicsOptions options, MLHandle opengl_context, MLHandle out_graphics_client)
Create the GL/GLES graphics client.
uint32_tMLGraphicsGLFormatFromMLSurfaceFormat(MLSurfaceFormat format)
Convert MLSurfaceFormat to OpenGL internal format.
MLSurfaceFormatMLGraphicsMLSurfaceFormatFromGLFormat(uint32_t format)
Convert OpenGL internal format to MLSurfaceFormat.
MLResultMLGraphicsCreateClientVk(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.
VkFormatMLGraphicsVkFormatFromMLSurfaceFormat(const MLSurfaceFormat format)
Convert MLSurfaceFormat to VkFormat.
MLSurfaceFormatMLGraphicsMLSurfaceFormatFromVkFormat(const VkFormat format)
Convert VkFormat to MLSurfaceFormat.
MLResultMLGraphicsDestroyClient(MLHandle * inout_graphics_client)
Destroy a GL/GLES or VK client.
MLResultMLGraphicsBeginFrameEx(MLHandle graphics_client, const MLGraphicsFrameParamsEx params, MLGraphicsFrameInfo out_frame_info)
Request to begin rendering a new frame in the graphics system.
MLResultMLGraphicsSignalSyncObjectGL(MLHandle graphics_client, MLHandle sync_object)
Signal the sync object provided for each virtual camera for GL/GLES clients.
MLResultMLGraphicsGetClipExtentsEx(MLHandle graphics_client, const MLGraphicsClipExtentsParams params, MLGraphicsClipExtentsInfoArrayEx out_array)
Get the conservative clip extents information for each virtual camera.
MLResultMLGraphicsGetRenderTargets(MLHandle graphics_client, MLGraphicsRenderTargetsInfo * out_targets)
Get a list of all buffered entries.
MLResultMLGraphicsEndFrame(MLHandle graphics_client, MLHandle handle)
Submit a completed frame to the graphics system.
MLResultMLGraphicsGetClientPerformanceInfo(MLHandle graphics_client, MLGraphicsClientPerformanceInfo * out_info)
Obtain latest performance metrics for the client.
MLResultMLGraphicsSetGlobalDimmer(MLHandle graphics_client, float dimmer_value)
Set the value for the global dimmer.

Enums Documentation

MLGraphicsFlags

EnumeratorValueDescription
MLGraphicsFlags_NoDepth1 << 0The 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_DebugMode1 << 2Create 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_Headlock1 << 3The 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_Default0When #graphics_flags is set to default, the client configuration returned is the default configuration (color/depth, origin lower left, non-debug, no headlock).
MLGraphicsFlags_Ensure32Bits0x7FFFFFFFEnsure 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

EnumeratorValueDescription
MLSurfaceFormat_Unknown0Invalid format for color/depth.
MLSurfaceFormat_RGBA8UNorm32bit linear color format (RGBA8).
MLSurfaceFormat_RGBA8UNormSRGBGamma 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_RGB10A2UNorm32bit linear color format (R10G10B10A2).
MLSurfaceFormat_RGBA16Float64bit linear color format (R16G16B16A16).
MLSurfaceFormat_D32Float32bit floating point depth buffer (D32F).
MLSurfaceFormat_D24NormS824bit linear depth format with 8bit stencil (D24S8).
MLSurfaceFormat_D32FloatS832bit floating point depth format with 8bit stencil (D32FS8).
MLSurfaceFormat_Ensure32Bits0x7FFFFFFFEnsure 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

EnumeratorValueDescription
MLGraphicsVirtualCameraName_Combined-1Name of the combined camera, the union of all virtual cameras.
MLGraphicsVirtualCameraName_Left0Name of virtual camera for left display.
MLGraphicsVirtualCameraName_RightName of virtual camera for right display.
MLGraphicsVirtualCameraName_CountThe maximum number of render virtual cameras.
MLGraphicsVirtualCameraName_Ensure32Bits0x7FFFFFFFEnsure 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

EnumeratorValueDescription
MLGraphics_BufferCount3The number of buffered entries for each virtual camera.

Definitions for Graphics system maximums.


MLGraphicsProjectionType

EnumeratorValueDescription
MLGraphicsProjectionType_SignedZ0Projection model with signed Z.
MLGraphicsProjectionType_ReversedInfiniteZ1Projection model reversed infinite Z.
MLGraphicsProjectionType_UnsignedZ2Projection model with unsigned Z.
MLGraphicsProjectionType_Ensure32Bits0x7FFFFFFFEnsure 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

EnumeratorValueDescription
MLGraphicsEnvironmentBlendMode_Additive0Ignore frame alpha and prohibit generation of segmented dimmer.
MLGraphicsEnvironmentBlendMode_Alpha_Blend1Use the resulting alpha after compostion potentially generating dimmer.
MLGraphicsEnvironmentBlendMode_Ensure32Bits0x7FFFFFFFEnsure 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

EnumeratorValueDescription
MLGraphicsBlobCache_DefaultMaxEntryBytes512 * 1024
MLGraphicsBlobCache_DefaultMaxTotalBytes8 * 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:

  • 21

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:

  • 4

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:

  • 4

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:

  • 27

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_paramsThe object to initialize with default settings.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 22

MLGraphicsClipExtentsParamsInit

static inline void MLGraphicsClipExtentsParamsInit(
MLGraphicsClipExtentsParams * inout_params
)

Initializes default values for MLGraphicsClipExtentsParams.

Parameters

MLGraphicsClipExtentsParams *inout_paramsThe object to initialize with default settings.
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 4

MLGraphicsClipExtentsInfoArrayExInit

static inline void MLGraphicsClipExtentsInfoArrayExInit(
MLGraphicsClipExtentsInfoArrayEx * inout_array
)

Initializes default values for MLGraphicsClipExtentsInfoArrayEx.

Parameters

MLGraphicsClipExtentsInfoArrayEx *inout_arrayThe object to initialize with default settings.
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 4

MLGraphicsFrameInfoInit

static inline void MLGraphicsFrameInfoInit(
MLGraphicsFrameInfo * inout_frame_info
)

Initializes default values for MLGraphicsFrameInfo.

Parameters

MLGraphicsFrameInfo *inout_frame_infoThe object to initialize with default settings.
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 27

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 *filenameAbsolute path to a file to use for caching. Location must be writeable by application.
uint32_tmax_entry_bytesReserved for future use. Maximum size for a single blob entry. Currently defaults to 512KB.
uint32_tmax_total_bytesReserved for future use. Maximum total file size for the blob. Currently defaults to 8MB.

Returns

MLResultMLResult_InvalidParamFailed to enable blob cache due to an invalid input parameter.
MLResultMLResult_OkSuccessfully 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 *optionsThe graphics options for resource creation.
MLHandleopengl_contextThe OpenGL context to use for resource creation.
MLHandle *out_graphics_clientThe handle to the created graphics client. Only valid if result is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to create graphics client due to an invalid input parameter.
MLResultMLResult_OkSuccessfully created graphics client.
MLResultMLResult_UnspecifiedFailureFailed 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

MLSurfaceFormatformatThe 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_tformatThe 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 *optionsThe graphics options for resource creation.
const VkInstancevulkan_instanceThe Vulkan instance used to create the physical and logical device.
const VkPhysicalDevicevulkan_physical_deviceThe Vulkan physical device used to create the specified logical device.
const VkDevicevulkan_logical_deviceThe Vulkan logical device to use for resource creation.
MLHandle *out_graphics_clientThe handle to the created graphics client. Only valid if result is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to create client due to an invalid input parameter.
MLResultMLResult_OkSuccessfully created client.
MLResultMLResult_UnspecifiedFailureFailed 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 MLSurfaceFormatformatThe 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 VkFormatformatThe 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_clientThe graphics client to destroy.

Returns

MLResultMLResult_InvalidParamFailed to destroy client due to an invalid input parameter.
MLResultMLResult_OkSuccessfully destroyed client.
MLResultMLResult_UnspecifiedFailureFailed 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

MLHandlegraphics_clientThe graphics client to query.
const MLGraphicsFrameParamsEx *paramsThe frame parameters for the frame.
MLGraphicsFrameInfo *out_frame_infoInformation returned for use when rendering the frame. Only valid if result is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to start frame due to an invalid input parameter.
MLResultMLResult_OkSuccessfully started frame.
MLResultMLResult_TimeoutFailed to start frame due to blocking timeout limit being reached.
MLResultMLResult_UnspecifiedFailureFailed 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:

  • 22

MLGraphicsSignalSyncObjectGL

MLResult MLGraphicsSignalSyncObjectGL(
MLHandle graphics_client,
MLHandle sync_object
)

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

Parameters

MLHandlegraphics_clientThe graphics client owning the sync object.
MLHandlesync_objectThe sync object to be signaled.

Returns

MLResultMLResult_InvalidParamFailed to signal object due to an invalid input parameter.
MLResultMLResult_OkSuccessfully signaled object.
MLResultMLResult_UnspecifiedFailureFailed 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

MLHandlegraphics_clientThe graphics client to query.
const MLGraphicsClipExtentsParams *paramsThe clip extents parameters.
MLGraphicsClipExtentsInfoArrayEx *out_arrayThe clip extents info array with all information required for update of each virtual camera. Only valid if result is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to obtain extents due to an invalid input parameter.
MLResultMLResult_OkSuccessfully obtained extents.
MLResultMLResult_UnspecifiedFailureFailed 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:

  • 4

MLGraphicsGetRenderTargets

MLResult MLGraphicsGetRenderTargets(
MLHandle graphics_client,
MLGraphicsRenderTargetsInfo * out_targets
)

Get a list of all buffered entries.

Parameters

MLHandlegraphics_clientThe graphics client to query.
MLGraphicsRenderTargetsInfo *out_targetsThe render target info array. Only valid if result is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to obtain target due to an invalid input parameter.
MLResultMLResult_OkSuccessfully obtained handle.
MLResultMLResult_UnspecifiedFailureFailed 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

MLHandlegraphics_clientThe graphics client to update.
MLHandlehandleThe handle provided from the call to MLGraphicsBeginFrameEx.

Returns

MLResultMLResult_InvalidParamFailed to end frame due to an invalid input parameter.
MLResultMLResult_OkSuccessfully ended frame.
MLResultMLResult_UnspecifiedFailureFailed 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

MLHandlegraphics_clientThe graphics client in which to query the performance.
MLGraphicsClientPerformanceInfo *out_infoCurrent performance information for the client. Only valid if result is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to obtain client performance metrics due to an invalid input parameter.
MLResultMLResult_OkSuccessfully obtained client performance metrics.
MLResultMLResult_UnspecifiedFailureFailed 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.


MLGraphicsSetGlobalDimmer

MLResult MLGraphicsSetGlobalDimmer(
MLHandle graphics_client,
float dimmer_value
)

Set the value for the global dimmer.

Parameters

MLHandlegraphics_clientThe graphics client handle.
floatdimmer_valueFloating point dimmer value in valid range [0.0 to 1.0]. 0.0 corresponds to min user defined value while 1.0 corresponds to max user defined value.

Returns

MLResultMLResult_InvalidParamAuto global dimmer value could not be set due to an invalid parameter.
MLResultMLResult_OkAuto global dimmer value set successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

Can be called any time after the client has been created. Updates are reflected in the next client submitted frame (via MLGraphicsEndFrame). Any smooth ramping from auto dimmer to application final dimmer should be handled by the application itself. Since the dimmer value set through MLGraphicsSetGlobalDimmer() is reflected only in the next client submitted frame, the smooth ramp stepping interval is equal to current application frame rate. Dimmer values correspond to a global dimming range defined by the user in the settings.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include "ml_api.h"
#include "ml_time.h"
#include "ml_types.h"

#include <string.h>

ML_EXTERN_C_BEGIN

typedef enum MLGraphicsFlags {
MLGraphicsFlags_NoDepth = 1 << 0,
MLGraphicsFlags_DebugMode = 1 << 2,
MLGraphicsFlags_Headlock = 1 << 3,
MLGraphicsFlags_Default = 0,
MLGraphicsFlags_Ensure32Bits = 0x7FFFFFFF
} MLGraphicsFlags;

typedef enum MLSurfaceFormat {
MLSurfaceFormat_Unknown = 0,
MLSurfaceFormat_RGBA8UNorm,
MLSurfaceFormat_RGBA8UNormSRGB,
MLSurfaceFormat_RGB10A2UNorm,
MLSurfaceFormat_RGBA16Float,
MLSurfaceFormat_D32Float,
MLSurfaceFormat_D24NormS8,
MLSurfaceFormat_D32FloatS8,
MLSurfaceFormat_Ensure32Bits = 0x7FFFFFFF
} MLSurfaceFormat;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsOptions {
uint32_t graphics_flags;
MLSurfaceFormat color_format;
MLSurfaceFormat depth_format;
} MLGraphicsOptions;

typedef enum MLGraphicsVirtualCameraName {
MLGraphicsVirtualCameraName_Combined = -1,
MLGraphicsVirtualCameraName_Left = 0,
MLGraphicsVirtualCameraName_Right,
MLGraphicsVirtualCameraName_Count,
MLGraphicsVirtualCameraName_Ensure32Bits = 0x7FFFFFFF
} MLGraphicsVirtualCameraName;

enum {
MLGraphics_BufferCount = 3
};

typedef enum MLGraphicsProjectionType {
MLGraphicsProjectionType_SignedZ = 0,
MLGraphicsProjectionType_ReversedInfiniteZ = 1,
MLGraphicsProjectionType_UnsignedZ = 2,
MLGraphicsProjectionType_Ensure32Bits = 0x7FFFFFFF
} MLGraphicsProjectionType;

typedef enum MLGraphicsEnvironmentBlendMode {
MLGraphicsEnvironmentBlendMode_Additive = 0,
MLGraphicsEnvironmentBlendMode_Alpha_Blend = 1,
MLGraphicsEnvironmentBlendMode_Ensure32Bits = 0x7FFFFFFF
} MLGraphicsEnvironmentBlendMode;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsFrameParamsEx {
uint32_t version;
float near_clip;
float far_clip;
float focus_distance;
float surface_scale;
bool vignette;
bool protected_surface;
MLGraphicsProjectionType projection_type;
MLGraphicsEnvironmentBlendMode blend_mode;
} MLGraphicsFrameParamsEx;

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_STATIC_INLINE void MLGraphicsFrameParamsExInit(MLGraphicsFrameParamsEx *inout_frame_params) {
inout_frame_params->version = 5;
inout_frame_params->near_clip = 0.5f;
inout_frame_params->far_clip = 10.0f;
inout_frame_params->focus_distance = 0.0f;
inout_frame_params->surface_scale = 1.0f;
inout_frame_params->vignette = false;
inout_frame_params->protected_surface = false;
inout_frame_params->projection_type = MLGraphicsProjectionType_SignedZ;
inout_frame_params->blend_mode = MLGraphicsEnvironmentBlendMode_Additive;
}

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsClipExtentsInfo {
MLGraphicsVirtualCameraName virtual_camera_name;
MLMat4f projection;
MLTransform transform;
} MLGraphicsClipExtentsInfo;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsClipExtentsParams {
uint32_t version;
} MLGraphicsClipExtentsParams;

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_STATIC_INLINE void MLGraphicsClipExtentsParamsInit(MLGraphicsClipExtentsParams *inout_params) {
inout_params->version = 1;
}

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsClipExtentsInfoArrayEx {
uint32_t version;
uint32_t num_virtual_cameras;
MLGraphicsClipExtentsInfo full_extents;
MLGraphicsClipExtentsInfo virtual_camera_extents[MLGraphicsVirtualCameraName_Count];
} MLGraphicsClipExtentsInfoArrayEx;

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_STATIC_INLINE void MLGraphicsClipExtentsInfoArrayExInit(MLGraphicsClipExtentsInfoArrayEx *inout_array) {
inout_array->version = 1;
inout_array->num_virtual_cameras = 0;
}

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsRenderTarget {
uint32_t width;
uint32_t height;
MLHandle id;
MLSurfaceFormat format;
} MLGraphicsRenderTarget;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsRenderBufferInfo {
MLGraphicsRenderTarget color;
MLGraphicsRenderTarget depth;
} MLGraphicsRenderBufferInfo;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsRenderTargetsInfo {
float min_clip;
float max_clip;
uint32_t num_virtual_cameras;
MLGraphicsRenderBufferInfo buffers[MLGraphics_BufferCount];
} MLGraphicsRenderTargetsInfo;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsVirtualCameraInfo {
float left_half_angle;
float right_half_angle;
float top_half_angle;
float bottom_half_angle;
MLHandle sync_object;
MLMat4f projection;
MLTransform transform;
MLGraphicsVirtualCameraName virtual_camera_name;
} MLGraphicsVirtualCameraInfo;

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsFrameInfo {
uint32_t version;
MLHandle handle;
MLHandle color_id;
MLHandle depth_id;
MLRectf viewport;
MLHandle wait_sync_object;
uint32_t num_virtual_cameras;
MLGraphicsVirtualCameraInfo virtual_cameras[MLGraphicsVirtualCameraName_Count];
MLTime predicted_display_time;
} MLGraphicsFrameInfo;

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_STATIC_INLINE void MLGraphicsFrameInfoInit(MLGraphicsFrameInfo *inout_frame_info) {
if (NULL != inout_frame_info) {
memset(inout_frame_info, 0, sizeof(MLGraphicsFrameInfo));
inout_frame_info->version = 3;
inout_frame_info->handle = (MLHandle)ML_INVALID_HANDLE;
}
}

typedef ML_DEPRECATED_MSG("Use OpenXR APIs.") struct MLGraphicsClientPerformanceInfo {
uint64_t frame_start_cpu_comp_acquire_cpu_ns;
uint64_t frame_start_cpu_frame_end_gpu_ns;
uint64_t frame_start_cpu_frame_start_cpu_ns;
uint64_t frame_duration_cpu_ns;
uint64_t frame_duration_gpu_ns;
uint64_t frame_internal_duration_cpu_ns;
uint64_t frame_internal_duration_gpu_ns;
} MLGraphicsClientPerformanceInfo;

enum {
MLGraphicsBlobCache_DefaultMaxEntryBytes = 512 * 1024,
MLGraphicsBlobCache_DefaultMaxTotalBytes = 8 * 1024 * 1024,
};

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsEnableBlobCacheGL(const char *filename, uint32_t max_entry_bytes, uint32_t max_total_bytes);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsCreateClientGL(const MLGraphicsOptions *options, MLHandle opengl_context, MLHandle *out_graphics_client);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API uint32_t ML_CALL MLGraphicsGLFormatFromMLSurfaceFormat(MLSurfaceFormat format);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLSurfaceFormat ML_CALL MLGraphicsMLSurfaceFormatFromGLFormat(uint32_t format);

#ifdef VK_VERSION_1_0

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsCreateClientVk(const MLGraphicsOptions *options, const VkInstance vulkan_instance, const VkPhysicalDevice vulkan_physical_device, const VkDevice vulkan_logical_device, MLHandle *out_graphics_client);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API VkFormat ML_CALL MLGraphicsVkFormatFromMLSurfaceFormat(const MLSurfaceFormat format);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLSurfaceFormat ML_CALL MLGraphicsMLSurfaceFormatFromVkFormat(const VkFormat format);
#endif

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsDestroyClient(MLHandle *inout_graphics_client);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsBeginFrameEx(MLHandle graphics_client, const MLGraphicsFrameParamsEx *params, MLGraphicsFrameInfo *out_frame_info);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsSignalSyncObjectGL(MLHandle graphics_client, MLHandle sync_object);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsGetClipExtentsEx(MLHandle graphics_client, const MLGraphicsClipExtentsParams *params, MLGraphicsClipExtentsInfoArrayEx *out_array);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsGetRenderTargets(MLHandle graphics_client, MLGraphicsRenderTargetsInfo *out_targets);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsEndFrame(MLHandle graphics_client, MLHandle handle);

ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsGetClientPerformanceInfo(MLHandle graphics_client, MLGraphicsClientPerformanceInfo *out_info);
ML_DEPRECATED_MSG("Use OpenXR APIs.")
ML_API MLResult ML_CALL MLGraphicsSetGlobalDimmer(MLHandle graphics_client, float dimmer_value);

ML_EXTERN_C_END