objc2_compositor_services/generated/

frame.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 objc2::__framework_prelude::*;

use crate::*;

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

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

/// An opaque type that provides access to the timing information and
/// data types you need to render a single frame of content.
///
/// During each cycle of your app’s rendering loop, retrieve a frame
/// using the ``cp_layer_renderer_query_next_frame`` function and use it to
/// render your app’s content. The ``cp_frame_t`` type provides access
/// to the information you need to render your frame in a timely manner.
/// It also provides access to the ``cp_drawable_t`` type you use to
/// retrieve the textures you need for drawing.
///
/// Separate the work you do for each frame into two phases: the update
/// phase and the encode phase. Use the update phase to perform app-specific
/// tasks, such as processing interactions with your content. Use the
/// encode phase to commit the Metal commands you need to draw your
/// content for the current pose. For both phases, use frame functions
/// to notify the Compositor when you start and stop the related work.
/// For example, surround update work with calls to the
/// ``cp_frame_start_update`` and ``cp_frame_end_update``
/// functions.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/compositorservices/cp_frame_t?language=objc)
pub type cp_frame_t = *mut cp_frame;

impl cp_frame {
    /// Returns the sequential index number of the specified frame.
    ///
    /// - Parameters:
    /// - frame: The frame to query.
    /// - Returns: The sequential index of the frame, which is always a
    /// positive integer.
    ///
    /// The layer assigns a unique index number to each frame, starting at
    /// the first frame and incrementing the index by 1 for each new frame.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_get_frame_index")]
    #[cfg(feature = "cp_types")]
    #[inline]
    pub unsafe fn frame_index(frame: cp_frame_t) -> cp_layer_frame_index_t {
        extern "C-unwind" {
            fn cp_frame_get_frame_index(frame: cp_frame_t) -> cp_layer_frame_index_t;
        }
        unsafe { cp_frame_get_frame_index(frame) }
    }

    /// Computes and returns the predicted timing information for the specified frame.
    ///
    /// - Parameters:
    /// - frame: The frame you're preparing to draw.
    /// - Returns: The predicted timing information for the specified frame, or `NULL`
    /// if the layer is in the ``cp_layer_renderer/cp_layer_renderer_state_paused`` or
    /// ``cp_layer_renderer/cp_layer_renderer_state_invalidated`` state.
    ///
    /// Use the returned timing information in any functions that return
    /// frame-related deadlines. For example, pass the timing information
    /// to the ``cp_frame_timing_get_optimal_input_time`` function to
    /// determine when to start encoding the frame. This function updates
    /// the frame-specific timing information using the latest data from
    /// the compositor before it returns it.
    ///
    /// Don’t call this function after you call ``cp_frame_query_drawable``
    /// for the specified frame. If you need the timing information after you
    /// retrieve the frame's ``cp_drawable_t`` type, save the return value
    /// of this function, or call ``cp_drawable_get_frame_timing`` to get
    /// the information from the drawable instead.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_predict_timing")]
    #[cfg(feature = "frame_timing")]
    #[inline]
    pub unsafe fn predict_timing(frame: cp_frame_t) -> cp_frame_timing_t {
        extern "C-unwind" {
            fn cp_frame_predict_timing(frame: cp_frame_t) -> cp_frame_timing_t;
        }
        unsafe { cp_frame_predict_timing(frame) }
    }

    /// Returns the drawable type you use to retrieve the textures and
    /// drawing environment for the frame.
    ///
    /// - Parameters:
    /// - frame: The frame to query.
    /// - Returns: The drawable type, or `NULL` if the layer is in the
    /// ``cp_layer_renderer/cp_layer_renderer_state_paused`` or
    /// ``cp_layer_renderer/cp_layer_renderer_state_invalidated`` state.
    ///
    /// Call this function when you're ready to encode the drawing commands
    /// for the frame. The ``cp_drawable_t`` type contains the textures and
    /// other information you need to set up your render descriptor in Metal.
    ///
    /// Note: This function isn't safe to be called concurrently. Always ensure a
    /// single thread call this function at a time.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_query_drawable")]
    #[cfg(feature = "drawable")]
    #[deprecated = "Use cp_frame_query_drawables instead"]
    #[inline]
    pub unsafe fn query_drawable(frame: cp_frame_t) -> cp_drawable_t {
        extern "C-unwind" {
            fn cp_frame_query_drawable(frame: cp_frame_t) -> cp_drawable_t;
        }
        unsafe { cp_frame_query_drawable(frame) }
    }

    /// Returns the drawable array type you use to retrieve the drawables for
    /// drawing environment for the frame.
    ///
    /// - Parameters:
    /// - frame: The frame to query.
    /// - Returns: The drawable array type, if the layer is in the
    /// ``cp_layer_renderer/cp_layer_renderer_state_paused`` or
    /// ``cp_layer_renderer/cp_layer_renderer_state_invalidated`` states
    /// the array will have a count of 0 and frame is invalid.
    ///
    /// Call this function when you're ready to encode the drawing commands
    /// for the frame. The ``cp_drawable_t`` type contains the textures and
    /// other information you need to set up your render descriptor in Metal.
    /// See ``cp_drawable_get_target`` for how each drawable will be used.
    ///
    /// If array count is 0, the frame has been cancelled as there are no drawables
    /// to draw to and the frame should be discarded and is invalid to access.
    ///
    /// Note: This function isn't safe to be called concurrently. Always ensure a
    /// single thread call this function at a time.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_query_drawables")]
    #[cfg(feature = "drawable")]
    #[inline]
    pub unsafe fn query_drawables(frame: cp_frame_t) -> cp_drawable_array_t {
        extern "C-unwind" {
            fn cp_frame_query_drawables(frame: cp_frame_t) -> cp_drawable_array_t;
        }
        unsafe { cp_frame_query_drawables(frame) }
    }

    /// Notifies the compositor that you started updating the app-specific
    /// content you need to render the frame.
    ///
    /// - Parameters:
    /// - frame: The frame you are ready to prepare.
    ///
    /// This function helps you optimize your app’s rendering efficiency.
    /// Before you render a frame, you might need to respond to
    /// interactions and update your app's data structures before you can
    /// render items in your scene.  Call this function immediately
    /// before you start that work, and call the ``cp_frame_end_update``
    /// function as soon as you finish. The compositor uses the time difference
    /// to improve its predictions for when to start the frame encoding process.
    ///
    /// Move as much work as possible into the update phase to minimize encoding
    /// time. Don't do any work that relies on the current pose information during
    /// the update phase. Instead, make any pose-related changes during the
    /// encoding phase.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_start_update")]
    #[inline]
    pub unsafe fn start_update(frame: cp_frame_t) {
        extern "C-unwind" {
            fn cp_frame_start_update(frame: cp_frame_t);
        }
        unsafe { cp_frame_start_update(frame) }
    }

    /// Notifies the compositor that you finished updating the app-specific
    /// content you need to render the frame.
    ///
    /// - Parameters:
    /// - frame: The frame you finished preparing.
    ///
    /// This function helps you optimize your app’s rendering efficiency.
    /// Before you render a frame, you might need to respond to
    /// interactions and update your app's data structures before you can
    /// render items in your scene. Call the ``cp_frame_start_update``
    /// function immediately before you start that work, and call this function
    /// as soon as you finish. Compositor uses the frame update time to improve
    /// its predictions for when to start the frame encoding process.
    ///
    /// Move as much work as possible into the update phase to minimize encoding
    /// time. Don't do any work that relies on the current pose information during
    /// the update phase. Instead, make any pose-related changes during the
    /// encoding phase.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_end_update")]
    #[inline]
    pub unsafe fn end_update(frame: cp_frame_t) {
        extern "C-unwind" {
            fn cp_frame_end_update(frame: cp_frame_t);
        }
        unsafe { cp_frame_end_update(frame) }
    }

    /// Notifies the compositor that you're ready to generate the
    /// GPU commands to render the specified frame.
    ///
    /// - Parameters:
    /// - frame: The frame you're ready to encode and send to the GPU.
    ///
    /// This function helps you optimize your app’s rendering efficiency.
    /// Call this function function before you start any of the GPU work that depends
    /// on the input data. Call the ``cp_frame_end_submission`` function after
    /// you finish your drawing commands and are ready to commit the frame to
    /// the GPU. Compositor uses the time difference to improve its predictions
    /// for when to start the frame submission process. Those predictions help
    /// you schedule the encoding process at a more optimal time for the
    /// system.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_start_submission")]
    #[inline]
    pub unsafe fn start_submission(frame: cp_frame_t) {
        extern "C-unwind" {
            fn cp_frame_start_submission(frame: cp_frame_t);
        }
        unsafe { cp_frame_start_submission(frame) }
    }

    /// Notifies the compositor that you finished generating the GPU
    /// commands to render the specified frame.
    ///
    /// - Parameters:
    /// - frame: The frame you're ready to submit to the GPU.
    ///
    /// This function helps you optimize your app’s rendering efficiency.
    /// Call the ``cp_frame_start_submission`` function before you start any of the GPU
    /// work that depends on the input data. Call this function after
    /// you finish your drawing commands and are ready to commit the frame to
    /// the GPU. Compositor uses the time difference to improve its predictions
    /// for when to start the frame submission process. Those predictions help
    /// you schedule the encoding process at a more optimal time for the
    /// system.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_end_submission")]
    #[inline]
    pub unsafe fn end_submission(frame: cp_frame_t) {
        extern "C-unwind" {
            fn cp_frame_end_submission(frame: cp_frame_t);
        }
        unsafe { cp_frame_end_submission(frame) }
    }

    /// Returns the number of view in the drawable target.
    ///
    /// - Parameters:
    /// - frame: frame: The frame you finished preparing.
    /// - drawable_target: whether this is intended for `built_in` or `recorder`drawable
    /// - Returns: The number of views available for drawing. For example, a return
    /// value of `2` indicates there are two views for this target drawable in this frame.
    /// value of `0` indicates there is no view available for this target drawable in this frame.
    ///
    /// Use the returned value as the maximum number of views to retrieve
    /// from the ``cp_frame_binocular_frustum_matrix_for_drawable_target``
    /// or ``cp_frame_monocular_frustum_matrix_for_drawable_target`` functions.
    ///
    /// # Safety
    ///
    /// `frame` must be a valid pointer.
    #[doc(alias = "cp_frame_get_drawable_target_view_count")]
    #[cfg(feature = "drawable")]
    #[inline]
    pub unsafe fn drawable_target_view_count(
        frame: cp_frame_t,
        drawable_target: cp_drawable_target,
    ) -> usize {
        extern "C-unwind" {
            fn cp_frame_get_drawable_target_view_count(
                frame: cp_frame_t,
                drawable_target: cp_drawable_target,
            ) -> usize;
        }
        unsafe { cp_frame_get_drawable_target_view_count(frame, drawable_target) }
    }
}

extern "C-unwind" {
    #[cfg(feature = "cp_types")]
    #[deprecated = "renamed to `cp_frame::frame_index`"]
    pub fn cp_frame_get_frame_index(frame: cp_frame_t) -> cp_layer_frame_index_t;
}

extern "C-unwind" {
    #[cfg(feature = "frame_timing")]
    #[deprecated = "renamed to `cp_frame::predict_timing`"]
    pub fn cp_frame_predict_timing(frame: cp_frame_t) -> cp_frame_timing_t;
}

extern "C-unwind" {
    #[cfg(feature = "drawable")]
    #[deprecated = "renamed to `cp_frame::query_drawable`"]
    pub fn cp_frame_query_drawable(frame: cp_frame_t) -> cp_drawable_t;
}

extern "C-unwind" {
    #[cfg(feature = "drawable")]
    #[deprecated = "renamed to `cp_frame::query_drawables`"]
    pub fn cp_frame_query_drawables(frame: cp_frame_t) -> cp_drawable_array_t;
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_frame::start_update`"]
    pub fn cp_frame_start_update(frame: cp_frame_t);
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_frame::end_update`"]
    pub fn cp_frame_end_update(frame: cp_frame_t);
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_frame::start_submission`"]
    pub fn cp_frame_start_submission(frame: cp_frame_t);
}

extern "C-unwind" {
    #[deprecated = "renamed to `cp_frame::end_submission`"]
    pub fn cp_frame_end_submission(frame: cp_frame_t);
}

extern "C-unwind" {
    #[cfg(feature = "drawable")]
    #[deprecated = "renamed to `cp_frame::drawable_target_view_count`"]
    pub fn cp_frame_get_drawable_target_view_count(
        frame: cp_frame_t,
        drawable_target: cp_drawable_target,
    ) -> usize;
}