Struct cp_drawable 

pub struct cp_drawable { /* private fields */ }

Available on crate feature drawable only.

Apple’s documentation

Implementations

impl cp_drawable

pub unsafe fn texture_count(drawable: cp_drawable_t) -> usize

Returns the number of color and depth textures available in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• Returns: The number of textures available for drawing. For example, a return value of 2 indicates there are two color textures and two depth textures available.

Use the returned value as the maximum number of textures to retrieve from the cp_drawable_get_color_texture or cp_drawable_get_depth_texture functions.

Safety

drawable must be a valid pointer.

pub unsafe fn tracking_areas_texture_count(drawable: cp_drawable_t) -> usize

Returns the number of tracking areas textures available in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• Returns: The number of textures available for drawing. For example, a return value of 2 indicates there are two tracking areas textures available.

Use the returned value as the maximum number of textures to retrieve from the cp_drawable_get_tracking_areas_texturefunction. This will be equal to cp_drawable_get_texture_count when tracking areas textures are enabled through the configuration otherwise will be 0.

Safety

drawable must be a valid pointer.

pub unsafe fn depth_texture( drawable: cp_drawable_t, index: usize, ) -> Retained<ProtocolObject<dyn MTLTexture>>

Available on crate feature objc2-metal only.

Returns the depth texture at the specified index in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• index: The index of the depth texture you want. The index must be greater than or equal to 0 and less than the value that cp_drawable_get_texture_count returns.
• Returns: The Metal depth texture at the specified index.

Use the returned texture in your render pipeline as the depth texture for your content. The layer’s texture topology determines the layout and content for each texture. The drawable’s views contain information about how those views map to the textures.

Safety

drawable must be a valid pointer.

pub unsafe fn color_texture( drawable: cp_drawable_t, index: usize, ) -> Retained<ProtocolObject<dyn MTLTexture>>

Available on crate feature objc2-metal only.

Returns the color texture at the specified index in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• index: The index of the color texture you want. The index must be greater than or equal to 0 and less than the value that cp_drawable_get_texture_count returns.
• Returns: The Metal color texture at the specified index.

Use the returned texture in your render pipeline to store the pixels you want to appear onscreen. The layer’s texture topology determines the layout and content for each texture. The drawable’s views contain information about how those views map to the textures.

Safety

drawable must be a valid pointer.

pub unsafe fn tracking_areas_texture( drawable: cp_drawable_t, index: usize, ) -> Retained<ProtocolObject<dyn MTLTexture>>

Available on crate feature objc2-metal only.

Returns the tracking areas texture at the specified index in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• index: The index of the texture you want. The index must be greater than or equal to 0 and less than the value that cp_drawable_get_tracking_areas_texture_count returns.
• Returns: The Metal object index texture at the specified index.

Use the returned texture in your render pipeline to store the tracking areas ID used for hover effects and indirect gestures. The layer’s texture topology determines the layout and content for each texture. The drawable’s views contain information about how those views map to the textures.

Safety

drawable must be a valid pointer.

pub unsafe fn add_tracking_area( drawable: cp_drawable_t, identifier: cp_tracking_area_identifier, ) -> cp_tracking_area_t

Available on crate feature tracking_area only.

Returns a tracking area which is create on the drawable’s list of tracking areas.

• Parameters:
• drawable: The drawable for a frame.
• identifier: The unique identifier for the tracking area.
• Returns: A tracking area that was created.

A tracking area describes a region of a view that interacts with the gaze/cursor. Cannot use cp_tracking_area_identifier_invalid as an identifier.

Safety

drawable must be a valid pointer.

pub unsafe fn rasterization_rate_map_count(drawable: cp_drawable_t) -> usize

Returns the number of rasterization rate maps associated with the drawable.

• Parameters:
• drawable: The drawable for a frame.
• Returns: The number of rasterization rate maps available for drawing.

Use the returned value as the maximum number of rate maps to retrieve from the cp_drawable_get_rasterization_rate_map function.

Safety

drawable must be a valid pointer.

pub unsafe fn rasterization_rate_map( drawable: cp_drawable_t, index: usize, ) -> Retained<ProtocolObject<dyn MTLRasterizationRateMap>>

Available on crate feature objc2-metal only.

Returns the rasterization rate map at the specified index in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• index: The index of the rasterization rate map you want. The index must be greater than or equal to 0 and less than the value that cp_drawable_get_rasterization_rate_map_count returns.
• Returns: The rasterization rate map at the specified index.

Apply the rasterization rate map to your render descriptor when you set up your drawing environment. A rate map defines how the GPU scales different parts of the texture to fill the screen. You use these rate maps to save time and render less important parts of your scene at lower resolutions. For example, when foveation is enabled, the drawable includes a rasterization rate map to render the portions of the texture in someone’s peripheral vision at a lower resolution.

Safety

drawable must be a valid pointer.

pub unsafe fn flipped_rasterization_rate_map( drawable: cp_drawable_t, index: usize, ) -> Retained<ProtocolObject<dyn MTLRasterizationRateMap>>

Available on crate feature objc2-metal only.

Returns the Y flipped rasterization rate map at the specified index in the drawable.

• Parameters:
• drawable: The drawable for a frame.
• index: The index of the rasterization rate map you want. The index must be greater than or equal to 0 and less than the value that cp_drawable_get_rasterization_rate_map_count returns.
• Returns: The Y flipped rasterization rate map at the specified index.

This function provides a Y flipped map that is generated form the cp_drawable_get_rasterization_rate_map. Flipped is defined as +Y = down for clip/normalized device coordinates (flipped from Metal). If projection matrix is needed, use cp_drawable_compute_projection with a +Y = down axes convention to generate the correct matrix.

Can only be used for intermediary render passes, the final render pass of the drawable it cannot be flipped and must use Metal convention of +Y = up.

Generating a flipped rasterization rate map will bring additional computational cost to your render loop.

In order to generate Y flipped rasterization rate maps in your rendering session, update the cp_layer_renderer_configuration_t using the function cp_layer_renderer_configuration_set_generate_flipped_rasterization_rate_maps.

Safety

drawable must be a valid pointer.

pub unsafe fn view_count(drawable: cp_drawable_t) -> usize

Returns the number of separate views to draw for the frame.

• Parameters:
• drawable: The drawable for a frame.
• Returns: The number of separate views to draw.

The number of views corresponds to the number of separate versions of your scene you create for the frame. For a device with stereoscopic video, you render two views — one for each eye. The actual number of views can vary based on the drawing environment or your app’s configuration. For example, you typically render only one view in Simulator.

Fetch the actual views using the cp_drawable_get_view function.

Safety

drawable must be a valid pointer.

pub unsafe fn view(drawable: cp_drawable_t, index: usize) -> cp_view_t

Available on crate feature view only.

Returns the specified view from the drawable.

• Parameters:
• drawable: The drawable for a frame.
• index: The index of the view you want. The index must be greater than or equal to 0 and less than the value that cp_drawable_get_view_count returns.
• Returns: The view at the specified index.

Each view contains information you need to render into the drawable’s textures.

Safety

drawable must be a valid pointer.

pub unsafe fn encode_present( drawable: cp_drawable_t, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, )

Available on crate feature objc2-metal only.

Encodes a notification event to the specified command buffer to present the drawable’s content onscreen.

• Parameters:

• drawable: The drawable for a frame.

• command_buffer: The command buffer you used to encode your frame’s content. If the command buffer is already committed, this function aborts your app with an error.

• Note: Commit the command buffer after calling present.

Call this function as the last step before committing the specified command buffer. Specifically, call it after you finish encoding all the work required to render the frame, and immediately before you call the command buffer’s <doc ://com.apple.documentation/documentation/metal/mtlcommandbuffer/1443003-commit> method. The function adds a presentation event to the buffer that causes the compositor to display your frame.

Safety

drawable must be a valid pointer.

pub unsafe fn mtl4_encode_present(drawable: cp_drawable_t)

Encodes a notification event to the specified command buffer to present the drawable’s content onscreen.

• Parameters:

• drawable: The drawable for a frame.

• Note: Commit the command buffer to the layer queue before calling present.

Call this function as the last step before committing the specified command buffer. Specifically, call it after you finish encoding all the work required to render the frame, and immediately before you call the command buffer’s <doc ://com.apple.documentation/documentation/metal/mtlcommandbuffer/1443003-commit> method. The function adds a presentation event to the buffer that causes the compositor to display your frame.

Safety

drawable must be a valid pointer.

pub unsafe fn state(drawable: cp_drawable_t) -> cp_drawable_state

Returns a value that indicates the current operational state of the drawable type.

• Parameters: The drawable to check.
• Returns: cp_drawable_state/cp_drawable_state_rendering if the drawable type is ready for you to draw your content, or any other value if the compositor currently owns the drawable.

Compositor reuses the underlying data structures associated with drawable types, and the state of the drawable indicates whether it’s ready for you to use. Perform your drawing operations only when the drawable is in the cp_drawable_state/cp_drawable_state_rendering state.

Safety

drawable must be a valid pointer.

pub unsafe fn target(drawable: cp_drawable_t) -> cp_drawable_target

Returns a value that indicates the target of the drawable type.

• Parameters: The drawable to check.
• Returns: cp_drawable_target/cp_drawable_target_built_in if the drawable will be displayed for the user in the device, or any other value if the drawable maybe used for other purposes.

When drawing for the drawable this can be used to alter what is rendered for different targets. Renderer should always prioritize cp_drawable_target/cp_drawable_target_built_in target type.

Safety

drawable must be a valid pointer.

pub unsafe fn presentation_frame_index( drawable: cp_drawable_t, ) -> cp_compositor_frame_index_t

Available on crate feature cp_types only.

Returns the index of the frame of content for you to produce.

• Parameters:
• drawable: The drawable for a frame.
• Returns: The presentation index of the frame.

When your compositor scene becomes visible, you start drawing frames of content. The compositor assigns a sequential index to each frame to indicate its position in the final output. You can use these indexes to differentiate frames during drawing or predict future frame indexes. For example, you might start playback of an audio file when a specific frame appears onscreen.

Safety

drawable must be a valid pointer.

pub unsafe fn frame_timing(drawable: cp_drawable_t) -> cp_frame_timing_t

Available on crate feature frame_timing only.

Returns the timing information for the frame of the specified drawable.

• Parameters:
• drawable: The drawable for a frame.
• Returns: The timing information for the drawable’s associated frame.

Pass the returned type to the cp_frame_timing_get_optimal_input_time function to determine when to start the encoding process for a frame. Pass it to other functions to determine other time-related deadlines.

Safety

drawable must be a valid pointer.

pub unsafe fn is_content_capture_protected(drawable: cp_drawable_t) -> bool

Returns whether content capture is protected and it is safe to draw content that should be protected from capture.

• Parameters:
• drawable: The drawable for a frame.
• Returns: Whether it is safe to draw content that is for built-in display only. When this value is true, any capture of content being displayed on the built-in display will be obscured by the system. If false, it cannot be assumed that content will not be seen by users outside of the device, both live and recorded.

Use this function to ensure that drawing that is only meant for eyes in the device is not drawn when false. Only adopt if app has adopted SwiftUI activatesContentCaptureProtected scene modifier and drawing will have content that is not desired to meant to be captured. For cp_drawable_target_capture this will always return false as it is upto the renderer to handle drawing content that will be captured beyond the built-in displays.

Safety

drawable must be a valid pointer.

pub unsafe fn add_render_context( drawable: cp_drawable_t, cmd_buffer: &ProtocolObject<dyn MTLCommandBuffer>, ) -> cp_drawable_render_context_t

Available on crate features drawable_render_context and objc2-metal only.

Adds a render context to a drawable. This object will draw any content that the compositor needs to render in the application.

• Note: The render context can only be used when the layer renderer is using layered layout or in platforms that only render one view (ex: simulator)

• Note: The render context makes use of the device_anchor set in cp_drawable_set_device_anchor the device_anchor should be set in the drawable before calling cp_drawable_add_render_context.

Safety

drawable must be a valid pointer.

pub unsafe fn add_mtl4_render_context( drawable: cp_drawable_t, ) -> cp_drawable_render_context_t

Available on crate feature drawable_render_context only.

Adds a render context to a drawable. This object will draw any content that the compositor needs to render in the application.

• Note: The render context can only be used when the layer renderer is using layered layout or in platforms that only render one view (ex: simulator)

• Note: The render context makes use of the device_anchor set in cp_drawable_set_device_anchor the device_anchor should be set in the drawable before calling cp_drawable_add_render_context.

Safety

drawable must be a valid pointer.

Trait Implementations

impl Debug for cp_drawable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl RefEncode for cp_drawable

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.