MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
Loading...
Searching...
No Matches
android.h File Reference

Go to the source code of this file.

Data Structures

struct  mln_android_surface_descriptor
struct  mln_android_surface_replacement
struct  mln_android_hardware_buffer_ring_descriptor
struct  mln_android_hardware_buffer_frame

Typedefs

typedef struct mln_android_surface_descriptor mln_android_surface_descriptor
typedef struct mln_android_surface_replacement mln_android_surface_replacement
typedef struct mln_android_hardware_buffer_ring_descriptor mln_android_hardware_buffer_ring_descriptor
typedef struct mln_android_hardware_buffer_frame mln_android_hardware_buffer_frame

Functions

mln_status mln_android_init (void *jni_env, void *context, mln_diagnostic *out_diagnostic)
mln_status mln_android_frame_pacer_create (const mln_frame_pacer_options *options, mln_frame_pacer *out_pacer, mln_diagnostic *out_diagnostic)
mln_status mln_map_attach_android_surface (mln_map map, const mln_android_surface_descriptor *descriptor, mln_vulkan_device device, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_render_session_set_android_surface_target (mln_render_session session, const mln_android_surface_replacement *replacement, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_map_attach_android_hardware_buffer_ring (mln_map map, const mln_android_hardware_buffer_ring_descriptor *descriptor, mln_vulkan_device device, const mln_render_session_attach_options *options, mln_render_session *out_session, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_acquired_frame_get_android_hardware_buffer (mln_acquired_frame frame, mln_android_hardware_buffer_frame *out_frame, mln_diagnostic *out_diagnostic)

Detailed Description

Set up the library in an Android app, present to its windows, render into hardware buffers, and pace its frames to the display.

Typedef Documentation

◆ mln_android_hardware_buffer_frame

typedef struct mln_android_hardware_buffer_frame mln_android_hardware_buffer_frame

The Android hardware buffer of an acquired frame.

◆ mln_android_hardware_buffer_ring_descriptor

typedef struct mln_android_hardware_buffer_ring_descriptor mln_android_hardware_buffer_ring_descriptor

A ring of Android hardware buffers that the library allocates, for mln_map_attach_android_hardware_buffer_ring().

Each buffer has the map's size in pixels, logical_size times the map's scale factor, and the format AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM. Its usage is AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT, AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE, and the bits of usage.

◆ mln_android_surface_descriptor

typedef struct mln_android_surface_descriptor mln_android_surface_descriptor

An Android window to present to, for mln_map_attach_android_surface().

Name the window by window, or by jni_env and surface. The session takes its own reference to the window, so you can release yours once the call returns.

◆ mln_android_surface_replacement

typedef struct mln_android_surface_replacement mln_android_surface_replacement

A new Android window for mln_render_session_set_android_surface_target().

Name the window by window, or by jni_env and surface. The session takes its own reference to the window, so you can release yours once the call returns.

Function Documentation

◆ mln_acquired_frame_get_android_hardware_buffer()

mln_status mln_acquired_frame_get_android_hardware_buffer ( mln_acquired_frame frame,
mln_android_hardware_buffer_frame * out_frame,
mln_diagnostic * out_diagnostic )

Gets the Android hardware buffer of an acquired frame.

Wait for mln_acquired_frame_get_producer_sync() before you read the buffer. Once you release or discard the frame, the session may render into the buffer again. A reference that you take with AHardwareBuffer_acquire keeps the buffer's memory, but not its contents.

Returns:

  • MLN_STATUS_TARGET_LOST when the session failed, or you detached, abandoned, or disposed it.

Lifetimes: The buffer in out_frame stays valid until you release or discard the frame, or the session is abandoned or disposed. A view from mln_acquired_frame_view_begin() keeps it valid until mln_acquired_frame_view_end().

◆ mln_android_frame_pacer_create()

mln_status mln_android_frame_pacer_create ( const mln_frame_pacer_options * options,
mln_frame_pacer * out_pacer,
mln_diagnostic * out_diagnostic )

Creates a frame pacer that follows the display through the calling thread's AChoreographer.

Call it on a thread with an ALooper, such as the app's main thread, and keep that thread running its looper while sessions use the pacer.

Returns:

  • MLN_STATUS_INVALID_STATE when the calling thread has no ALooper.

◆ mln_android_init()

mln_status mln_android_init ( void * jni_env,
void * context,
mln_diagnostic * out_diagnostic )

Gives the library the Java VM and the app context that it needs on Android.

Call it before creating a runtime. jni_env is the calling thread's JNIEnv*, and context is an Android Context, such as the application.

◆ mln_map_attach_android_hardware_buffer_ring()

mln_status mln_map_attach_android_hardware_buffer_ring ( mln_map map,
const mln_android_hardware_buffer_ring_descriptor * descriptor,
mln_vulkan_device device,
const mln_render_session_attach_options * options,
mln_render_session * out_session,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Creates a session that renders the map into a ring of Android hardware buffers that the library allocates.

Acquire each frame with mln_render_session_acquire_frame(), and get its buffer with mln_acquired_frame_get_android_hardware_buffer(). mln_render_session_resize() gives the ring new buffers of the new size.

A Vulkan build renders with device, or, when device is null, with a device that the library creates. An OpenGL build uses an EGL context on the default display, and device must be null. Attach with MLN_RENDER_DRIVER_CORE_WORKER.

To show the buffers through Android's UI, such as with Bitmap.wrapHardwareBuffer, attach without MLN_GPU_SYNC_KIND_FLAG_SYNC_FD in mln_render_session_attach_options.producer_sync_kinds, so that each frame finishes before you acquire it. Keep each frame acquired until the next one replaces it on screen, then release it with MLN_GPU_SYNC_CPU_COMPLETE. Give the ring 3 buffers, so the session can render while you hold two frames.

Returns:

  • MLN_STATUS_UNSUPPORTED when Android is older than 8.0, API level 26, or when the graphics context can't render into hardware buffers: the Vulkan device lacks VK_ANDROID_external_memory_android_hardware_buffer, or the EGL display lacks EGL_ANDROID_get_native_client_buffer or EGL_ANDROID_image_native_buffer.
  • MLN_STATUS_NATIVE_ERROR when the library can't create its Vulkan device or initialize the default EGL display.

◆ mln_map_attach_android_surface()

mln_status mln_map_attach_android_surface ( mln_map map,
const mln_android_surface_descriptor * descriptor,
mln_vulkan_device device,
const mln_render_session_attach_options * options,
mln_render_session * out_session,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Creates a session that presents the map to an Android window, with a graphics context that the library creates.

A Vulkan build presents with device, or, when device is null, with a device that the library creates. An OpenGL build uses an EGL context on the default display, and device must be null. Attach with MLN_RENDER_DRIVER_CORE_WORKER.

When the platform destroys the window, such as in SurfaceHolder.Callback.surfaceDestroyed, release the target with mln_render_session_release_target(), or give the session a new window with mln_render_session_set_android_surface_target(), without waiting for that to complete. The session keeps its own reference to the window and stays usable for the next window. A frame to the destroyed window finishes with MLN_RENDER_RESULT_TARGET_NOT_READY, or with MLN_RENDER_RESULT_RENDERED if the window went away while the frame was presenting.

Returns:

  • MLN_STATUS_INVALID_ARGUMENT when surface has no window, such as after the platform destroyed it.
  • MLN_STATUS_UNSUPPORTED when you created device without mln_vulkan_device_options.presentation.

Completes with:

  • MLN_STATUS_UNSUPPORTED when the GPU or the Vulkan loader can't present.
  • MLN_STATUS_NATIVE_ERROR when the library can't create the graphics context or the window's surface.

◆ mln_render_session_set_android_surface_target()

mln_status mln_render_session_set_android_surface_target ( mln_render_session session,
const mln_android_surface_replacement * replacement,
const mln_completion * completion,
mln_diagnostic * out_diagnostic )

Replaces the Android window that the session presents to.

Use it to give the session a window again after mln_render_session_release_target(), to move it to another window, or to resize it. Once the replacement completes, the session no longer uses the old window.

Returns:

  • MLN_STATUS_INVALID_ARGUMENT when surface has no window, such as after the platform destroyed it.

Completes with:

  • MLN_STATUS_UNSUPPORTED when, in a Vulkan build, the new window needs a different color format or pre-rotation support than the old one. Attach a new session instead.
  • MLN_STATUS_NATIVE_ERROR when the library can't create the window's surface.