Skip to main content
Version: 21 Aug 2024

ml_native_surface.h

Classes

Name
structMLNativeSurfaceFrameAvailableInfo
NativeSurface/NativeSurfaceTexture Output Frame Availability information.
structMLNativeSurfaceConfig
Configuration values for creating the Native Surface.
structMLNativeSurfaceOnFrameAvailableCallback
Callbacks for notifying when an output frame is available for consumption.

Types

Name
typedef struct MLNativeSurfaceFrameAvailableInfoMLNativeSurfaceFrameAvailableInfo
NativeSurface/NativeSurfaceTexture Output Frame Availability information.
typedef struct MLNativeSurfaceConfigMLNativeSurfaceConfig
Configuration values for creating the Native Surface.
typedef struct MLNativeSurfaceOnFrameAvailableCallbackMLNativeSurfaceOnFrameAvailableCallback
Callbacks for notifying when an output frame is available for consumption.

Enums

Name
enumMLNativeSurfaceAcquiredBufferCount
{
MLNativeSurfaceAcquiredBufferCount_Min = 1,
MLNativeSurfaceAcquiredBufferCount_Max = 16,
MLNativeSurfaceAcquiredBufferCount_Ensure32Bits = 0x7FFFFFFF
}
Number of acquired buffers to be requested in functions MLNativeSurfaceCreate and MLNativeSurfaceTextureCreate.
enumMLNativeSurfacePixelFormat
{
MLNativeSurfacePixelFormat_Custom = -4,
MLNativeSurfacePixelFormat_Translucent = -3,
MLNativeSurfacePixelFormat_Transparent = -2,
MLNativeSurfacePixelFormat_Opaque = -1,
MLNativeSurfacePixelFormat_None = 0,
MLNativeSurfacePixelFormat_Rgba8888 = 1,
MLNativeSurfacePixelFormat_Rgbx8888 = 2,
MLNativeSurfacePixelFormat_Rgb888 = 3,
MLNativeSurfacePixelFormat_Rgb565 = 4,
MLNativeSurfacePixelFormat_Bgra8888 = 5,
MLNativeSurfacePixelFormat_RgbaFp16 = 22,
MLNativeSurfacePixelFormat_Rgba1010102 = 43,
MLNativeSurfacePixelFormat_Ensure32Bits = 0x7FFFFFFF
}
Pixel format to use when creating the native surface. Used in functions MLNativeSurfaceCreate and MLNativeSurfaceTextureCreate.
enumMLNativeSurfaceTextureBackend
{
MLNativeSurfaceTextureBackend_OpenGL = 0,
MLNativeSurfaceTextureBackend_Ensure32Bits = 0x7FFFFFFF
}

Functions

Name
voidMLNativeSurfaceConfigInit(MLNativeSurfaceConfig * inout_config_values)
Initializes MLNativeSurfaceConfig with default values.
voidMLNativeSurfaceOnFrameAvailableCallbackInit(MLNativeSurfaceOnFrameAvailableCallback * inout_callbacks)
Initializes MLNativeSurfaceOnFrameAvailableCallback with default values.
MLResultMLNativeSurfaceCreate(const MLNativeSurfaceConfig config_values, MLHandle out_handle)
Create a new NativeSurface.
MLResultMLNativeSurfaceRelease(MLHandle handle)
Release a NativeSurface.
MLResultMLNativeSurfaceGetNativeWindow(MLHandle handle, MLHandle out_native_window, int32_t out_format)
Gets an implementation of NativeWindow that feeds graphic buffers into MLNativeSurface.
MLResultMLNativeSurfaceReleaseNativeWindow(MLHandle handle, MLHandle native_window)
Releases NativeWindow previously acquired by MLNativeSurfaceGetNativeWindow.
MLResultMLNativeSurfaceAcquireNextAvailableFrame(MLHandle handle, MLHandle * out_native_buffer)
Consume next available buffer.
MLResultMLNativeSurfaceAcquireHardwareBufferFromNativeBuffer(MLHandle handle, MLHandle native_buffer, struct AHardwareBuffer * out_hardware_buffer, uint32_t out_width, uint32_t * out_height)
Acquire an AHardwareBuffer* from a native buffer handle.
MLResultMLNativeSurfaceReleaseFrame(MLHandle handle, MLHandle native_buffer)
Release a native buffer previously acquired.
MLResultMLNativeSurfaceGetFrameTransformationMatrix(MLHandle handle, float out_mtx[16])
Retrieves the 4x4 texture coordinate transform matrix associated with the last acquired Frame.
MLResultMLNativeSurfaceGetFrameTimestamp(MLHandle handle, int64_t * out_timestamp_ns)
Retrieves the timestamp associated with the last acquired frame. The timestamp is in nanoseconds, and is monotonically increasing from beginning of the playback. Its other semantics (zero point, etc) are codec-dependent and should be documented by the codec vendor.
MLResultMLNativeSurfaceGetFrameQueueBufferTimestamp(MLHandle handle, int64_t * out_timestamp_ns)
Retrieves the QueueBuffer timestamp associated with the last acquired Frame This timestamp is for profiling purposes only and corresponds to the time when this frame was queued by internal Codec's producer code. The timestamp is in nanoseconds, and is monotonically increasing from beginning of playback. Its other semantics (zero point, etc) are codec-dependent and should by documented by the codec vendor.
MLResultMLNativeSurfaceGetFrameNumber(MLHandle handle, uint64_t * out_number)
Retrieves the last acquired frame number. The frame number is an incrementing counter set to 0 at Codec configuration time.
MLResultMLNativeSurfaceGetFrameCropRect(MLHandle handle, MLRecti * out_crop_rect)
Retrieves the cropping rectangle of the current frame/buffer.
MLResultMLNativeSurfaceSetOnFrameAvailableCallback(MLHandle handle, const MLNativeSurfaceOnFrameAvailableCallback callback, void user_data)
Set callback to notify client when a frame is available.
MLResultMLNativeSurfaceTextureCreate(const MLNativeSurfaceConfig config_values, MLNativeSurfaceTextureBackend backend, MLHandle out_handle)
Create a new NativeSurfaceTexture.
MLResultMLNativeSurfaceTextureRelease(MLHandle handle)
Release a NativeSurfaceTexture.
MLResultMLNativeSurfaceTextureUpdateTexImage(MLHandle handle)
Update the texture image to the most recent frame from the image stream.
MLResultMLNativeSurfaceTextureAttachToGLContext(MLHandle handle, uint32_t texture_id)
Attach the NativeSurfaceTexture to the graphic context that is current on the calling thread.
MLResultMLNativeSurfaceTextureDetachFromGLContext(MLHandle handle)
Detach the NativeSurfaceTexture from the graphic context that owns the graphic texture object.
MLResultMLNativeSurfaceTextureGetTransformationMatrix(MLHandle handle, float out_matrix[16])
Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to MLNativeSurfaceTextureUpdateTexImage.
MLResultMLNativeSurfaceTextureGetTimestamp(MLHandle handle, int64_t * out_timestamp_ns)
Retrieve the timestamp associated with the texture image set by the most recent call to MLNativeSurfaceTextureUpdateTexImage.
MLResultMLNativeSurfaceTextureSetOnFrameAvailableCallback(MLHandle handle, const MLNativeSurfaceOnFrameAvailableCallback callback, void user_data)
Set callback to notify client when a frame is available.

Enums Documentation

MLNativeSurfaceAcquiredBufferCount

EnumeratorValueDescription
MLNativeSurfaceAcquiredBufferCount_Min1Min number of buffer count.
MLNativeSurfaceAcquiredBufferCount_Max16Max number of buffer count.
MLNativeSurfaceAcquiredBufferCount_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Number of acquired buffers to be requested in functions MLNativeSurfaceCreate and MLNativeSurfaceTextureCreate.


MLNativeSurfacePixelFormat

EnumeratorValueDescription
MLNativeSurfacePixelFormat_Custom-4Custom format.
MLNativeSurfacePixelFormat_Translucent-3Translucent format.
MLNativeSurfacePixelFormat_Transparent-2Transparent format.
MLNativeSurfacePixelFormat_Opaque-1Opaque format.
MLNativeSurfacePixelFormat_None0None.
MLNativeSurfacePixelFormat_Rgba88881Below enums should match android_pixel_format_t in graphics-base-v1.0.h header.4x8-bit RGBA format.
MLNativeSurfacePixelFormat_Rgbx888824x8-bit RGBX format.
MLNativeSurfacePixelFormat_Rgb88833x8-bit RGB format.
MLNativeSurfacePixelFormat_Rgb565416-bit RGB format.
MLNativeSurfacePixelFormat_Bgra888854x8-bit BGRA format.
MLNativeSurfacePixelFormat_RgbaFp162264-bit RGBA format.
MLNativeSurfacePixelFormat_Rgba10101024332-bit RGBA format.
MLNativeSurfacePixelFormat_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Pixel format to use when creating the native surface. Used in functions MLNativeSurfaceCreate and MLNativeSurfaceTextureCreate.


MLNativeSurfaceTextureBackend

EnumeratorValueDescription
MLNativeSurfaceTextureBackend_OpenGL0OpenGL texture.
MLNativeSurfaceTextureBackend_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Graphic backend to use.

API Level:

  • 20

Types Documentation

MLNativeSurfaceFrameAvailableInfo

typedef struct MLNativeSurfaceFrameAvailableInfo MLNativeSurfaceFrameAvailableInfo;

NativeSurface/NativeSurfaceTexture Output Frame Availability information.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceConfig

typedef struct MLNativeSurfaceConfig MLNativeSurfaceConfig;

Configuration values for creating the Native Surface.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceOnFrameAvailableCallback

typedef struct MLNativeSurfaceOnFrameAvailableCallback MLNativeSurfaceOnFrameAvailableCallback;

Callbacks for notifying when an output frame is available for consumption.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

Functions Documentation

MLNativeSurfaceConfigInit

static inline void MLNativeSurfaceConfigInit(
MLNativeSurfaceConfig * inout_config_values
)

Initializes MLNativeSurfaceConfig with default values.

Parameters

MLNativeSurfaceConfig *inout_config_valuesMLNativeSurfaceConfig structure defined by MLNativeSurfaceConfig that needs to be initialized.

MLNativeSurfaceOnFrameAvailableCallbackInit

static inline void MLNativeSurfaceOnFrameAvailableCallbackInit(
MLNativeSurfaceOnFrameAvailableCallback * inout_callbacks
)

Initializes MLNativeSurfaceOnFrameAvailableCallback with default values.

Parameters

MLNativeSurfaceOnFrameAvailableCallback *inout_callbacksMLNativeSurfaceOnFrameAvailableCallback Callback structure defined by MLNativeSurfaceOnFrameAvailableCallback that needs to be initialized.
Deprecated

Deprecated since 1.4.0. Scheduled for removal.


MLNativeSurfaceCreate

MLResult MLNativeSurfaceCreate(
const MLNativeSurfaceConfig * config_values,
MLHandle * out_handle
)

Create a new NativeSurface.

Parameters

const MLNativeSurfaceConfig *config_valuesConfiguration values for creating the native surface, refer MLNativeSurfaceConfig for more details.
MLHandle *out_handleUpon successful return will point to handle to the created NativeSurface. Or else, it will point to ML_INVALID_HANDLE.

Returns

MLResultMLResult_AllocFailedFailed to allocate memory for surface.
MLResultMLResult_InvalidParamOne of the parameters is invalid.
MLResultMLResult_OkNativeSurface object was created successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

The NativeSurface created through this API should be released using MLNativeSurfaceRelease once done using it.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceRelease

MLResult MLNativeSurfaceRelease(
MLHandle handle
)

Release a NativeSurface.

Parameters

MLHandlehandleMLHandle to the NativeSurface.

Returns

MLResultMLResult_InvalidParamNativeSurface object is invalid.
MLResultMLResult_OkNativeSurface object was successfully released.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceGetNativeWindow

MLResult MLNativeSurfaceGetNativeWindow(
MLHandle handle,
MLHandle * out_native_window,
int32_t * out_format
)

Gets an implementation of NativeWindow that feeds graphic buffers into MLNativeSurface.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance. This handle can be:

* Surface created on an Encoder using MLMediaCodecCreateInputSurface. * The output surface created using MLNativeSurfaceCreate. * The output surface created using MLNativeSurfaceTextureCreate. | | MLHandle |out_native_window|Native window as MLHandle on success. | | int32_t |out_format|Native window format on success and for valid pointer, which will be used as EGL_NATIVE_VISUAL_ID.|

Returns

MLResultMLResult_InvalidParamNativeSurface object is invalid or out_native_window is NULL.
MLResultMLResult_OkNative window is successfully retrieved.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

This function returns the platform-dependent native window typically used by Graphics API or HW decoders to render frames.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceReleaseNativeWindow

MLResult MLNativeSurfaceReleaseNativeWindow(
MLHandle handle,
MLHandle native_window
)

Releases NativeWindow previously acquired by MLNativeSurfaceGetNativeWindow.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
MLHandlenative_windowNative window handle acquired through MLNativeSurfaceGetNativeWindow.

Returns

MLResultMLResult_InvalidParamNativeSurface or NativeWindow object is invalid.
MLResultMLResult_OkNative window is successfully released.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.


MLNativeSurfaceAcquireNextAvailableFrame

MLResult MLNativeSurfaceAcquireNextAvailableFrame(
MLHandle handle,
MLHandle * out_native_buffer
)

Consume next available buffer.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
MLHandle *out_native_bufferA pointer to the acquired native buffer of the frame. When buffer is not required anymore, caller must call MLNativeSurfaceReleaseFrame() with this nativeBuffer handle to free up queuing space for incoming buffers.

Returns

MLResultMLResult_InvalidParamOne of the parameters is invalid.
MLResultMLResult_OkNext available frame is acquired successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.
MLResultMLMediaGenericResult_NotEnoughDataNative buffer is not available yet to acquire.

Required Permissions:

  • None

Note: This function is non-blocking and should only be called from the rendering thread after #on_frame_available callback has been fired.

Note: The returned buffer's color format is multi-planar YUV420. Since our underlying hardware interops do not support multiplanar formats, advanced texture features like mipmaping, anisotropic filtering and MSAA will not work on those returned buffers. If such advanced texturing features are required, one has to acquire the YUV buffers as usual and render to an RGB texture and only then, will one be able to enable hardware optimization for such advanced texture features.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceAcquireHardwareBufferFromNativeBuffer

MLResult MLNativeSurfaceAcquireHardwareBufferFromNativeBuffer(
MLHandle handle,
MLHandle native_buffer,
struct AHardwareBuffer ** out_hardware_buffer,
uint32_t * out_width,
uint32_t * out_height
)

Acquire an AHardwareBuffer* from a native buffer handle.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance. Pass ML_INVALID_HANDLE when using with native buffers acquired without a MLNativeSurface, like in the case of ml_webview api.
MLHandlenative_bufferThe native buffer handle acquired from a MLNativeSurfaceAcquireNextAvailableFrame call.
struct AHardwareBuffer **out_hardware_bufferThe AHardwareBuffer pointer to the imported surface.
uint32_t *out_widthWidth of the imported surface.
uint32_t *out_heightHeight of the imported surface.

Returns

MLResultMLResult_InvalidParamImport was not performed due to an invalid parameter.
MLResultMLResult_OkSurface was acquired successfully.
MLResultMLResult_UnspecifiedFailureImport was not performed due to an unknown error.

Required Permissions:

  • None

The AHardwareBuffer* can be used with the Vulkan extension VK_ANDROID_external_memory_android_hardware_buffer to get the hardware buffer format properties, which can then be used to bind this hardware buffer to a VkImage. Caller is responsible for releasing the AHardwareBuffer by calling AHardwareBuffer_release() after its usage.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceReleaseFrame

MLResult MLNativeSurfaceReleaseFrame(
MLHandle handle,
MLHandle native_buffer
)

Release a native buffer previously acquired.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
MLHandlenative_bufferThe native buffer for the frame to release.

Returns

MLResultMLResult_InvalidParamOne of the parameters is invalid.
MLResultMLResult_OkFrame was released successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceGetFrameTransformationMatrix

MLResult MLNativeSurfaceGetFrameTransformationMatrix(
MLHandle handle,
float out_mtx[16]
)

Retrieves the 4x4 texture coordinate transform matrix associated with the last acquired Frame.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
floatout_mtxA pointer to an array of 16 floats that will receive retrieved transformation matrix.

Required Permissions:

  • None

This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample that location from the texture. Sampling the texture outside of the range of this transform is undefined.

This transform is necessary to compensate for transforms that the stream content producer may implicitly apply to the content. By forcing users of a GLConsumer to apply this transform we avoid performing an extra copy of the data that would be needed to hide the transform from the user.

The matrix is stored in column-major order.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

Return:

  • MLResult_InvalidParam One of the parameters is invalid.
  • MLResult_Ok Transformation matrix was returned.

API Level:

  • 20

MLNativeSurfaceGetFrameTimestamp

MLResult MLNativeSurfaceGetFrameTimestamp(
MLHandle handle,
int64_t * out_timestamp_ns
)

Retrieves the timestamp associated with the last acquired frame. The timestamp is in nanoseconds, and is monotonically increasing from beginning of the playback. Its other semantics (zero point, etc) are codec-dependent and should be documented by the codec vendor.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
int64_t *out_timestamp_nsA pointer to user variable for storing retrieved timestamp.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

Return:

  • MLResult_InvalidParam One of the parameters is invalid.
  • MLResult_Ok Timestamp was returned.

API Level:

  • 20

MLNativeSurfaceGetFrameQueueBufferTimestamp

MLResult MLNativeSurfaceGetFrameQueueBufferTimestamp(
MLHandle handle,
int64_t * out_timestamp_ns
)

Retrieves the QueueBuffer timestamp associated with the last acquired Frame This timestamp is for profiling purposes only and corresponds to the time when this frame was queued by internal Codec's producer code. The timestamp is in nanoseconds, and is monotonically increasing from beginning of playback. Its other semantics (zero point, etc) are codec-dependent and should by documented by the codec vendor.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
int64_t *out_timestamp_nsA pointer to user variable for storing retrieved timestamp.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

Return:

  • MLResult_InvalidParam One of the parameters is invalid.
  • MLResult_Ok Timestamp was returned.

API Level:

  • 20

MLNativeSurfaceGetFrameNumber

MLResult MLNativeSurfaceGetFrameNumber(
MLHandle handle,
uint64_t * out_number
)

Retrieves the last acquired frame number. The frame number is an incrementing counter set to 0 at Codec configuration time.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
uint64_t *out_numberA pointer to user variable for storing retrieved frame number.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

Return:

  • MLResult_InvalidParam One of the parameters is invalid.
  • MLResult_Ok Frame number was returned.

API Level:

  • 20

MLNativeSurfaceGetFrameCropRect

MLResult MLNativeSurfaceGetFrameCropRect(
MLHandle handle,
MLRecti * out_crop_rect
)

Retrieves the cropping rectangle of the current frame/buffer.

Parameters

MLHandlehandleMLHandle to the MLNativeSurface instance.
MLRecti *out_crop_rectA pointer to user variable for storing retrieved Crop.

Required Permissions:

  • None

The Frame crop is returned as {left, bottom, width, height}.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

Return:

  • MLResult_InvalidParam One of the parameters is invalid.
  • MLResult_Ok Frame Crop was returned.

API Level:

  • 20

MLNativeSurfaceSetOnFrameAvailableCallback

MLResult MLNativeSurfaceSetOnFrameAvailableCallback(
MLHandle handle,
const MLNativeSurfaceOnFrameAvailableCallback * callback,
void * user_data
)

Set callback to notify client when a frame is available.

Parameters

MLHandlehandleMLHandle to the NativeSurface.
const MLNativeSurfaceOnFrameAvailableCallback *callbackA MLNativeSurfaceOnFrameAvailableCallback function.
void *user_dataPointer to user payload data.

Returns

MLResultMLResult_InvalidParamMLNativeSurface object is invalid.
MLResultMLResult_OkCallback was set successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureCreate

MLResult MLNativeSurfaceTextureCreate(
const MLNativeSurfaceConfig * config_values,
MLNativeSurfaceTextureBackend backend,
MLHandle * out_handle
)

Create a new NativeSurfaceTexture.

Parameters

const MLNativeSurfaceConfig *config_valuesConfiguration values for creating the native surface, refer MLNativeSurfaceConfig for more details.
MLNativeSurfaceTextureBackendbackendThe graphic backend to use.
MLHandle *out_handleUpon successful return will point to handle to the created NativeSurfaceTexture. Or else, it will point to ML_INVALID_HANDLE.

Returns

MLResultMLResult_AllocFailedFailed to allocate memory for surface.
MLResultMLResult_InvalidParamOne of the parameters is invalid.
MLResultMLResult_OkNativeSurfaceTexture object was created successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureRelease

MLResult MLNativeSurfaceTextureRelease(
MLHandle handle
)

Release a NativeSurfaceTexture.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_OkNativeSurfaceTexture object was successfully released.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureUpdateTexImage

MLResult MLNativeSurfaceTextureUpdateTexImage(
MLHandle handle
)

Update the texture image to the most recent frame from the image stream.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_Okthe texture was updated successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

May only be called on the thread with the graphic context that contains the texture object.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureAttachToGLContext

MLResult MLNativeSurfaceTextureAttachToGLContext(
MLHandle handle,
uint32_t texture_id
)

Attach the NativeSurfaceTexture to the graphic context that is current on the calling thread.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.
uint32_ttexture_idThe graphic texture object id.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_Okthe texture was detached successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureDetachFromGLContext

MLResult MLNativeSurfaceTextureDetachFromGLContext(
MLHandle handle
)

Detach the NativeSurfaceTexture from the graphic context that owns the graphic texture object.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_Okthe texture was detached successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

If called on the thread with graphic context that contains the attached texture object, said texture will be deleted.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureGetTransformationMatrix

MLResult MLNativeSurfaceTextureGetTransformationMatrix(
MLHandle handle,
float out_matrix[16]
)

Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to MLNativeSurfaceTextureUpdateTexImage.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.
floatout_matrixA 4x4 matrix stored in column-major order as 16 consecutive values.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_OkOperation was successful.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureGetTimestamp

MLResult MLNativeSurfaceTextureGetTimestamp(
MLHandle handle,
int64_t * out_timestamp_ns
)

Retrieve the timestamp associated with the texture image set by the most recent call to MLNativeSurfaceTextureUpdateTexImage.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.
int64_t *out_timestamp_nsThe timestamp in nanoseconds.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_OkOperation was successful.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

MLNativeSurfaceTextureSetOnFrameAvailableCallback

MLResult MLNativeSurfaceTextureSetOnFrameAvailableCallback(
MLHandle handle,
const MLNativeSurfaceOnFrameAvailableCallback * callback,
void * user_data
)

Set callback to notify client when a frame is available.

Parameters

MLHandlehandleMLHandle to the NativeSurfaceTexture.
const MLNativeSurfaceOnFrameAvailableCallback *callbackA MLNativeSurfaceTextureOnFrameAvailableCallback function.
void *user_dataPointer to user payload data.

Returns

MLResultMLResult_InvalidParamNativeSurfaceTexture object is invalid.
MLResultMLResult_OkCallback was set successfully.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

  • 20

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2021 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_types.h"

ML_EXTERN_C_BEGIN

typedef enum MLNativeSurfaceAcquiredBufferCount{
MLNativeSurfaceAcquiredBufferCount_Min = 1,
MLNativeSurfaceAcquiredBufferCount_Max = 16,
MLNativeSurfaceAcquiredBufferCount_Ensure32Bits = 0x7FFFFFFF
}MLNativeSurfaceAcquiredBufferCount;

typedef enum MLNativeSurfacePixelFormat {
MLNativeSurfacePixelFormat_Custom = -4,
MLNativeSurfacePixelFormat_Translucent = -3,
MLNativeSurfacePixelFormat_Transparent = -2,
MLNativeSurfacePixelFormat_Opaque = -1,
MLNativeSurfacePixelFormat_None = 0,
MLNativeSurfacePixelFormat_Rgba8888 = 1,
MLNativeSurfacePixelFormat_Rgbx8888 = 2,
MLNativeSurfacePixelFormat_Rgb888 = 3,
MLNativeSurfacePixelFormat_Rgb565 = 4,
MLNativeSurfacePixelFormat_Bgra8888 = 5,
MLNativeSurfacePixelFormat_RgbaFp16 = 22,
MLNativeSurfacePixelFormat_Rgba1010102 = 43,
MLNativeSurfacePixelFormat_Ensure32Bits = 0x7FFFFFFF
} MLNativeSurfacePixelFormat;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLNativeSurfaceFrameAvailableInfo {
void *user_data;
} MLNativeSurfaceFrameAvailableInfo;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLNativeSurfaceConfig {
uint32_t version;

MLNativeSurfacePixelFormat pixel_format;

uint16_t buffer_count;

uint32_t width;

uint32_t height;

} MLNativeSurfaceConfig;

ML_STATIC_INLINE void MLNativeSurfaceConfigInit(MLNativeSurfaceConfig *inout_config_values)
{
if (inout_config_values) {
inout_config_values->version = 1;
inout_config_values->width = 0;
inout_config_values->height = 0;
inout_config_values->buffer_count = 1;
}
}

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLNativeSurfaceOnFrameAvailableCallback {
uint32_t version;

void (*on_frame_available)(MLHandle handle, const MLNativeSurfaceFrameAvailableInfo *info);
} MLNativeSurfaceOnFrameAvailableCallback;

ML_STATIC_INLINE void MLNativeSurfaceOnFrameAvailableCallbackInit(MLNativeSurfaceOnFrameAvailableCallback *inout_callbacks) {
if (inout_callbacks) {
inout_callbacks->version = 1;
inout_callbacks->on_frame_available = NULL;
}
}

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceCreate(const MLNativeSurfaceConfig *config_values, MLHandle* out_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceRelease(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceGetNativeWindow(MLHandle handle, MLHandle *out_native_window, int32_t *out_format);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceReleaseNativeWindow(MLHandle handle, MLHandle native_window);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceAcquireNextAvailableFrame(MLHandle handle, MLHandle *out_native_buffer);

struct AHardwareBuffer;

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceAcquireHardwareBufferFromNativeBuffer(MLHandle handle, MLHandle native_buffer, struct AHardwareBuffer **out_hardware_buffer, uint32_t *out_width, uint32_t *out_height);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceReleaseFrame(MLHandle handle, MLHandle native_buffer);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceGetFrameTransformationMatrix(MLHandle handle, float out_mtx[16]);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceGetFrameTimestamp(MLHandle handle, int64_t *out_timestamp_ns);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceGetFrameQueueBufferTimestamp(MLHandle handle, int64_t *out_timestamp_ns);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceGetFrameNumber(MLHandle handle, uint64_t *out_number);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceGetFrameCropRect(MLHandle handle, MLRecti *out_crop_rect);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceSetOnFrameAvailableCallback(MLHandle handle, const MLNativeSurfaceOnFrameAvailableCallback *callback, void *user_data);

typedef enum MLNativeSurfaceTextureBackend {
MLNativeSurfaceTextureBackend_OpenGL = 0,
MLNativeSurfaceTextureBackend_Ensure32Bits = 0x7FFFFFFF
} MLNativeSurfaceTextureBackend;

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureCreate(const MLNativeSurfaceConfig *config_values, MLNativeSurfaceTextureBackend backend,
MLHandle *out_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureRelease(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureUpdateTexImage(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureAttachToGLContext(MLHandle handle, uint32_t texture_id);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureDetachFromGLContext(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureGetTransformationMatrix(MLHandle handle, float out_matrix[16]);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureGetTimestamp(MLHandle handle, int64_t *out_timestamp_ns);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLNativeSurfaceTextureSetOnFrameAvailableCallback(MLHandle handle,
const MLNativeSurfaceOnFrameAvailableCallback *callback, void *user_data);

ML_EXTERN_C_END