objc2_compositor_services/generated/

drawable.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::cell::UnsafeCell;
use core::ffi::*;
use core::marker::{PhantomData, PhantomPinned};
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-metal")]
use objc2_metal::*;

use crate::*;

/// The state of ownership for the drawable.
///
/// Use these constants to determine whether the drawable is ready
/// for you to use. When the drawable is in the ``cp_drawable_state_rendering``
/// state, you can begin drawing. Other states indicate the
/// drawable is either busy or not assigned to a frame.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/compositorservices/cp_drawable_state?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct cp_drawable_state(pub u32);
impl cp_drawable_state {
    /// A drawable that is not in use and ready for assignment to a frame.
    #[doc(alias = "cp_drawable_state_available")]
    pub const available: Self = Self(0);
    /// A drawable that is assigned to a frame and ready to accept
    /// your drawing commands.
    #[doc(alias = "cp_drawable_state_rendering")]
    pub const rendering: Self = Self(1);
    /// A drawable that the compositor is currently displaying onscreen.
    #[doc(alias = "cp_drawable_state_presenting")]
    pub const presenting: Self = Self(2);
}

unsafe impl Encode for cp_drawable_state {
    const ENCODING: Encoding = u32::ENCODING;
}

unsafe impl RefEncode for cp_drawable_state {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// [Apple's documentation](https://developer.apple.com/documentation/compositorservices/cp_drawable?language=objc)
#[repr(C)]
#[derive(Debug)]
pub struct cp_drawable {
    inner: [u8; 0],
    _p: UnsafeCell<PhantomData<(*const UnsafeCell<()>, PhantomPinned)>>,
}

unsafe impl RefEncode for cp_drawable {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Encoding::Struct("cp_drawable", &[]));
}

/// An opaque type that contains the textures and other information
/// you need to set up your render pipeline.
///
/// Use the drawable type to retrieve the textures for your render pipelines,
/// and use the drawable’s views to get details about how to render to those
/// textures. Get the drawable for a frame using the ``cp_frame_query_drawable``
/// function. The layer manages a limited number of reusable drawable types
/// and recycles them after each use. Draw only one frame at a time to ensure
/// each new frame’s drawable type is ready in time.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/compositorservices/cp_drawable_t?language=objc)
pub type cp_drawable_t = *mut cp_drawable;

impl cp_drawable {
    /// 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.
    #[doc(alias = "cp_drawable_get_texture_count")]
    #[inline]
    pub unsafe fn texture_count(drawable: cp_drawable_t) -> usize {
        extern "C-unwind" {
            fn cp_drawable_get_texture_count(drawable: cp_drawable_t) -> usize;
        }
        unsafe { cp_drawable_get_texture_count(drawable) }
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_depth_texture")]
    #[cfg(feature = "objc2-metal")]
    #[inline]
    pub unsafe fn depth_texture(
        drawable: cp_drawable_t,
        index: usize,
    ) -> Retained<ProtocolObject<dyn MTLTexture>> {
        extern "C-unwind" {
            fn cp_drawable_get_depth_texture(
                drawable: cp_drawable_t,
                index: usize,
            ) -> *mut ProtocolObject<dyn MTLTexture>;
        }
        let ret = unsafe { cp_drawable_get_depth_texture(drawable, index) };
        unsafe { Retained::retain_autoreleased(ret) }
            .expect("function was marked as returning non-null, but actually returned NULL")
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_color_texture")]
    #[cfg(feature = "objc2-metal")]
    #[inline]
    pub unsafe fn color_texture(
        drawable: cp_drawable_t,
        index: usize,
    ) -> Retained<ProtocolObject<dyn MTLTexture>> {
        extern "C-unwind" {
            fn cp_drawable_get_color_texture(
                drawable: cp_drawable_t,
                index: usize,
            ) -> *mut ProtocolObject<dyn MTLTexture>;
        }
        let ret = unsafe { cp_drawable_get_color_texture(drawable, index) };
        unsafe { Retained::retain_autoreleased(ret) }
            .expect("function was marked as returning non-null, but actually returned NULL")
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_rasterization_rate_map_count")]
    #[inline]
    pub unsafe fn rasterization_rate_map_count(drawable: cp_drawable_t) -> usize {
        extern "C-unwind" {
            fn cp_drawable_get_rasterization_rate_map_count(drawable: cp_drawable_t) -> usize;
        }
        unsafe { cp_drawable_get_rasterization_rate_map_count(drawable) }
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_rasterization_rate_map")]
    #[cfg(feature = "objc2-metal")]
    #[inline]
    pub unsafe fn rasterization_rate_map(
        drawable: cp_drawable_t,
        index: usize,
    ) -> Retained<ProtocolObject<dyn MTLRasterizationRateMap>> {
        extern "C-unwind" {
            fn cp_drawable_get_rasterization_rate_map(
                drawable: cp_drawable_t,
                index: usize,
            ) -> *mut ProtocolObject<dyn MTLRasterizationRateMap>;
        }
        let ret = unsafe { cp_drawable_get_rasterization_rate_map(drawable, index) };
        unsafe { Retained::retain_autoreleased(ret) }
            .expect("function was marked as returning non-null, but actually returned NULL")
    }

    /// 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``.
    #[doc(alias = "cp_drawable_get_flipped_rasterization_rate_map")]
    #[cfg(feature = "objc2-metal")]
    #[inline]
    pub unsafe fn flipped_rasterization_rate_map(
        drawable: cp_drawable_t,
        index: usize,
    ) -> Retained<ProtocolObject<dyn MTLRasterizationRateMap>> {
        extern "C-unwind" {
            fn cp_drawable_get_flipped_rasterization_rate_map(
                drawable: cp_drawable_t,
                index: usize,
            ) -> *mut ProtocolObject<dyn MTLRasterizationRateMap>;
        }
        let ret = unsafe { cp_drawable_get_flipped_rasterization_rate_map(drawable, index) };
        unsafe { Retained::retain_autoreleased(ret) }
            .expect("function was marked as returning non-null, but actually returned NULL")
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_view_count")]
    #[inline]
    pub unsafe fn view_count(drawable: cp_drawable_t) -> usize {
        extern "C-unwind" {
            fn cp_drawable_get_view_count(drawable: cp_drawable_t) -> usize;
        }
        unsafe { cp_drawable_get_view_count(drawable) }
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_view")]
    #[cfg(feature = "view")]
    #[inline]
    pub unsafe fn view(drawable: cp_drawable_t, index: usize) -> cp_view_t {
        extern "C-unwind" {
            fn cp_drawable_get_view(drawable: cp_drawable_t, index: usize) -> cp_view_t;
        }
        unsafe { cp_drawable_get_view(drawable, index) }
    }

    /// 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.
    ///
    /// 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.
    #[doc(alias = "cp_drawable_encode_present")]
    #[cfg(feature = "objc2-metal")]
    #[inline]
    pub unsafe fn encode_present(
        drawable: cp_drawable_t,
        command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
    ) {
        extern "C-unwind" {
            fn cp_drawable_encode_present(
                drawable: cp_drawable_t,
                command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
            );
        }
        unsafe { cp_drawable_encode_present(drawable, command_buffer) }
    }

    /// Returns a value that indicates the current operational state
    /// of the drawable type.
    ///
    /// - Parameters: The drawable to test.
    /// - 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.
    #[doc(alias = "cp_drawable_get_state")]
    #[inline]
    pub unsafe fn state(drawable: cp_drawable_t) -> cp_drawable_state {
        extern "C-unwind" {
            fn cp_drawable_get_state(drawable: cp_drawable_t) -> cp_drawable_state;
        }
        unsafe { cp_drawable_get_state(drawable) }
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_presentation_frame_index")]
    #[cfg(feature = "cp_types")]
    #[inline]
    pub unsafe fn presentation_frame_index(drawable: cp_drawable_t) -> cp_compositor_frame_index_t {
        extern "C-unwind" {
            fn cp_drawable_get_presentation_frame_index(
                drawable: cp_drawable_t,
            ) -> cp_compositor_frame_index_t;
        }
        unsafe { cp_drawable_get_presentation_frame_index(drawable) }
    }

    /// 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.
    #[doc(alias = "cp_drawable_get_frame_timing")]
    #[cfg(feature = "frame_timing")]
    #[inline]
    pub unsafe fn frame_timing(drawable: cp_drawable_t) -> cp_frame_timing_t {
        extern "C-unwind" {
            fn cp_drawable_get_frame_timing(drawable: cp_drawable_t) -> cp_frame_timing_t;
        }
        unsafe { cp_drawable_get_frame_timing(drawable) }
    }
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_drawable::texture_count`"]
    pub fn cp_drawable_get_texture_count(drawable: cp_drawable_t) -> usize;
}

#[cfg(feature = "objc2-metal")]
#[deprecated = "renamed to `cp_drawable::depth_texture`"]
#[inline]
pub unsafe extern "C-unwind" fn cp_drawable_get_depth_texture(
    drawable: cp_drawable_t,
    index: usize,
) -> Retained<ProtocolObject<dyn MTLTexture>> {
    extern "C-unwind" {
        fn cp_drawable_get_depth_texture(
            drawable: cp_drawable_t,
            index: usize,
        ) -> *mut ProtocolObject<dyn MTLTexture>;
    }
    let ret = unsafe { cp_drawable_get_depth_texture(drawable, index) };
    unsafe { Retained::retain_autoreleased(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}

#[cfg(feature = "objc2-metal")]
#[deprecated = "renamed to `cp_drawable::color_texture`"]
#[inline]
pub unsafe extern "C-unwind" fn cp_drawable_get_color_texture(
    drawable: cp_drawable_t,
    index: usize,
) -> Retained<ProtocolObject<dyn MTLTexture>> {
    extern "C-unwind" {
        fn cp_drawable_get_color_texture(
            drawable: cp_drawable_t,
            index: usize,
        ) -> *mut ProtocolObject<dyn MTLTexture>;
    }
    let ret = unsafe { cp_drawable_get_color_texture(drawable, index) };
    unsafe { Retained::retain_autoreleased(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_drawable::rasterization_rate_map_count`"]
    pub fn cp_drawable_get_rasterization_rate_map_count(drawable: cp_drawable_t) -> usize;
}

#[cfg(feature = "objc2-metal")]
#[deprecated = "renamed to `cp_drawable::rasterization_rate_map`"]
#[inline]
pub unsafe extern "C-unwind" fn cp_drawable_get_rasterization_rate_map(
    drawable: cp_drawable_t,
    index: usize,
) -> Retained<ProtocolObject<dyn MTLRasterizationRateMap>> {
    extern "C-unwind" {
        fn cp_drawable_get_rasterization_rate_map(
            drawable: cp_drawable_t,
            index: usize,
        ) -> *mut ProtocolObject<dyn MTLRasterizationRateMap>;
    }
    let ret = unsafe { cp_drawable_get_rasterization_rate_map(drawable, index) };
    unsafe { Retained::retain_autoreleased(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}

#[cfg(feature = "objc2-metal")]
#[deprecated = "renamed to `cp_drawable::flipped_rasterization_rate_map`"]
#[inline]
pub unsafe extern "C-unwind" fn cp_drawable_get_flipped_rasterization_rate_map(
    drawable: cp_drawable_t,
    index: usize,
) -> Retained<ProtocolObject<dyn MTLRasterizationRateMap>> {
    extern "C-unwind" {
        fn cp_drawable_get_flipped_rasterization_rate_map(
            drawable: cp_drawable_t,
            index: usize,
        ) -> *mut ProtocolObject<dyn MTLRasterizationRateMap>;
    }
    let ret = unsafe { cp_drawable_get_flipped_rasterization_rate_map(drawable, index) };
    unsafe { Retained::retain_autoreleased(ret) }
        .expect("function was marked as returning non-null, but actually returned NULL")
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_drawable::view_count`"]
    pub fn cp_drawable_get_view_count(drawable: cp_drawable_t) -> usize;
}

extern "C-unwind" {
    #[cfg(feature = "view")]
    #[deprecated = "renamed to `cp_drawable::view`"]
    pub fn cp_drawable_get_view(drawable: cp_drawable_t, index: usize) -> cp_view_t;
}

extern "C-unwind" {
    #[cfg(feature = "objc2-metal")]
    #[deprecated = "renamed to `cp_drawable::encode_present`"]
    pub fn cp_drawable_encode_present(
        drawable: cp_drawable_t,
        command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
    );
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_drawable::state`"]
    pub fn cp_drawable_get_state(drawable: cp_drawable_t) -> cp_drawable_state;
}

extern "C-unwind" {
    #[cfg(feature = "cp_types")]
    #[deprecated = "renamed to `cp_drawable::presentation_frame_index`"]
    pub fn cp_drawable_get_presentation_frame_index(
        drawable: cp_drawable_t,
    ) -> cp_compositor_frame_index_t;
}

extern "C-unwind" {
    #[cfg(feature = "frame_timing")]
    #[deprecated = "renamed to `cp_drawable::frame_timing`"]
    pub fn cp_drawable_get_frame_timing(drawable: cp_drawable_t) -> cp_frame_timing_t;
}