apple.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_io_surface_ring_descriptor
struct	mln_io_surface_frame

Typedefs
typedef struct mln_io_surface_ring_descriptor	mln_io_surface_ring_descriptor
typedef struct mln_io_surface_frame	mln_io_surface_frame

Functions
mln_status	mln_apple_frame_pacer_create (const mln_frame_pacer_options *options, mln_frame_pacer *out_pacer, mln_diagnostic *out_diagnostic)
mln_status	mln_map_attach_io_surface_ring (mln_map map, const mln_io_surface_ring_descriptor *descriptor, 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_io_surface (mln_acquired_frame frame, mln_io_surface_frame *out_frame, mln_diagnostic *out_diagnostic)

Detailed Description

Render into IOSurfaces, and pace the library's frames to the display, on Apple platforms.

Typedef Documentation

mln_io_surface_frame

typedef struct mln_io_surface_frame mln_io_surface_frame

The IOSurface of an acquired frame.

mln_io_surface_ring_descriptor

typedef struct mln_io_surface_ring_descriptor mln_io_surface_ring_descriptor

A ring of IOSurfaces that the library allocates, for mln_map_attach_io_surface_ring().

Each surface has the map's size in pixels, logical_size times the map's scale factor, and the pixel format kCVPixelFormatType_32BGRA, which Metal names MTLPixelFormatBGRA8Unorm.

Function Documentation

mln_acquired_frame_get_io_surface()

mln_status mln_acquired_frame_get_io_surface	(	mln_acquired_frame	frame,
		mln_io_surface_frame *	out_frame,
		mln_diagnostic *	out_diagnostic )

Gets the IOSurface of an acquired frame.

Wait for mln_acquired_frame_get_producer_sync() before you read the surface. Once you release or discard the frame, the session may render into the surface again. For an API that takes a CVPixelBuffer, wrap the surface with CVPixelBufferCreateWithIOSurface. A reference that you take with CFRetain, or a pixel buffer that wraps the surface, keeps the surface's memory, but not its contents.

Returns:

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

Lifetimes: The surface 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_apple_frame_pacer_create()

mln_status mln_apple_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 a CADisplayLink.

You can call it on any thread. The pacer needs no run loop of yours. On macOS, it follows the main display, the one with the menu bar.

With mln_frame_pacer_options.maximum_frames_per_second, the pacer also asks the system for that refresh rate. On iPhone, a rate above 60 needs CADisableMinimumFrameDurationOnPhone in the app's Info.plist.

Returns:

• MLN_STATUS_NATIVE_ERROR when the system has no display to follow.

mln_map_attach_io_surface_ring()

mln_status mln_map_attach_io_surface_ring	(	mln_map	map,
		const mln_io_surface_ring_descriptor *	descriptor,
		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 IOSurfaces that the library allocates.

Acquire each frame with mln_render_session_acquire_frame(), and get its surface with mln_acquired_frame_get_io_surface(). mln_render_session_resize() gives the ring new surfaces of the new size. Attach with MLN_RENDER_DRIVER_CORE_WORKER.

To hand frames to a reader that can't wait on an event, such as Flutter's copyPixelBuffer, attach without MLN_GPU_SYNC_KIND_FLAG_METAL_SHARED_EVENT in mln_render_session_attach_options.producer_sync_kinds, so that each frame finishes before you acquire it. Release a frame with MLN_GPU_SYNC_CPU_COMPLETE only once the reader has finished with its surface.

Returns:

• MLN_STATUS_UNSUPPORTED when mln_supported_render_backend_mask() lacks MLN_RENDER_BACKEND_FLAG_METAL.
• MLN_STATUS_NATIVE_ERROR when context names no device and the system has no Metal device.