The open source OpenXR runtime
xrt: Improve doc comments in compositor header
+66
-26
+66
-26
src/xrt/include/xrt/xrt_compositor.h
+66
-26
src/xrt/include/xrt/xrt_compositor.h
···
734
734
*
735
735
* The only requirement on the compositor for the @p frame_id
736
736
* is that it is a positive number.
737
+
*
738
+
* If the caller can do its own blocking, use the pair of functions
739
+
* xrt_compositor::predict_frame and xrt_compositor::mark_frame instead
740
+
* of this single blocking function.
737
741
*/
738
742
xrt_result_t (*wait_frame)(struct xrt_compositor *xc,
739
743
int64_t *out_frame_id,
···
746
750
xrt_result_t (*begin_frame)(struct xrt_compositor *xc, int64_t frame_id);
747
751
748
752
/*!
753
+
* @brief Explicitly discard a frame.
754
+
*
749
755
* This isn't in the OpenXR API but is explicit in the XRT interfaces.
750
756
*
751
-
* Two calls to xrBeginFrame will cause the state tracker to call.
757
+
* Two calls to xrBeginFrame without intervening xrEndFrame will cause
758
+
* the state tracker to call:
752
759
*
753
760
* ```c
754
-
* xc->begin_frame(xc, frame_id)
755
-
* xc->discard_frame(xc, frame_id)
756
-
* xc->begin_frame(xc, frame_id)
761
+
* // first xrBeginFrame
762
+
* xrt_comp_begin_frame(xc, frame_id);
763
+
* // second xrBeginFrame
764
+
* xrt_comp_discard_frame(xc, frame_id);
765
+
* xrt_comp_begin_frame(xc, frame_id);
757
766
* ```
758
767
*/
759
768
xrt_result_t (*discard_frame)(struct xrt_compositor *xc, int64_t frame_id);
760
769
761
770
/*!
762
-
* Begins layer submission, this and the other layer_* calls are
763
-
* equivalent to xrEndFrame, except over multiple calls. It's only after
764
-
* @p layer_commit that layers will be displayed. From the point of view
765
-
* of the swapchain the image is used as soon as it's given in a call.
771
+
* @brief Begins layer submission.
772
+
*
773
+
* This and the other `layer_*` calls are equivalent to xrEndFrame,
774
+
* except split over multiple calls. It's only after
775
+
* xrt_compositor::layer_commit that layers will be displayed.
776
+
* From the point of view of the swapchain, the image is used as
777
+
* soon as it's given in a call.
766
778
*/
767
779
xrt_result_t (*layer_begin)(struct xrt_compositor *xc,
768
780
int64_t frame_id,
···
770
782
enum xrt_blend_mode env_blend_mode);
771
783
772
784
/*!
773
-
* Adds a stereo projection layer for submissions.
785
+
* @brief Adds a stereo projection layer for submissions.
786
+
*
787
+
* Note that e.g. the same swapchain object may be passed as both
788
+
* @p l_xsc and @p r_xsc - the parameters in @p data identify
789
+
* the subrect and array texture index to use for each of the views.
774
790
*
775
791
* @param xc Self pointer
776
792
* @param xdev The device the layer is relative to.
777
-
* @param l_xsc Left swapchain.
778
-
* @param r_xsc Right swapchain.
779
-
* @param data All of the pure data bits.
793
+
* @param l_xsc Swapchain object containing left eye RGB data.
794
+
* @param r_xsc Swapchain object containing right eye RGB data.
795
+
* @param data All of the pure data bits (not pointers/handles),
796
+
* including what parts of the supplied swapchain
797
+
* objects to use for each view.
780
798
*/
781
799
xrt_result_t (*layer_stereo_projection)(struct xrt_compositor *xc,
782
800
struct xrt_device *xdev,
···
785
803
const struct xrt_layer_data *data);
786
804
787
805
/*!
788
-
* Adds a stereo projection layer for submission, has depth information.
806
+
* @brief Adds a stereo projection layer for submission, has depth information.
807
+
*
808
+
* Note that e.g. the same swapchain object may be passed as both
809
+
* @p l_xsc and @p r_xsc - the parameters in @p data identify
810
+
* the subrect and array texture index to use for each of the views.
811
+
* This flexibility is required by the OpenXR API and is passed through
812
+
* to the compositor to preserve the maximum information
789
813
*
790
814
* @param xc Self pointer
791
815
* @param xdev The device the layer is relative to.
792
-
* @param l_xsc Left swapchain.
793
-
* @param r_xsc Right swapchain.
794
-
* @param l_d_xsc Left depth swapchain.
795
-
* @param r_d_xsc Right depth swapchain.
796
-
* @param data All of the pure data bits.
816
+
* @param l_xsc Swapchain object containing left eye RGB data.
817
+
* @param r_xsc Swapchain object containing right eye RGB data.
818
+
* @param l_d_xsc Swapchain object containing left eye depth data.
819
+
* @param r_d_xsc Swapchain object containing right eye depth data.
820
+
* @param data All of the pure data bits (not pointers/handles),
821
+
* including what parts of the supplied swapchain
822
+
* objects to use for each view.
797
823
*/
798
824
xrt_result_t (*layer_stereo_projection_depth)(struct xrt_compositor *xc,
799
825
struct xrt_device *xdev,
···
810
836
* @param xc Self pointer
811
837
* @param xdev The device the layer is relative to.
812
838
* @param xsc Swapchain.
813
-
* @param data All of the pure data bits.
839
+
* @param data All of the pure data bits (not pointers/handles),
840
+
* including what part of the supplied swapchain
841
+
* object to use.
814
842
*/
815
843
xrt_result_t (*layer_quad)(struct xrt_compositor *xc,
816
844
struct xrt_device *xdev,
···
823
851
* @param xc Self pointer
824
852
* @param xdev The device the layer is relative to.
825
853
* @param xsc Swapchain.
826
-
* @param data All of the pure data bits.
854
+
* @param data All of the pure data bits (not pointers/handles),
855
+
* including what part of the supplied swapchain
856
+
* object to use.
827
857
*/
828
858
xrt_result_t (*layer_cube)(struct xrt_compositor *xc,
829
859
struct xrt_device *xdev,
···
836
866
* @param xc Self pointer
837
867
* @param xdev The device the layer is relative to.
838
868
* @param xsc Swapchain.
839
-
* @param data All of the pure data bits.
869
+
* @param data All of the pure data bits (not pointers/handles),
870
+
* including what part of the supplied swapchain
871
+
* object to use.
840
872
*/
841
873
xrt_result_t (*layer_cylinder)(struct xrt_compositor *xc,
842
874
struct xrt_device *xdev,
···
849
881
* @param xc Self pointer
850
882
* @param xdev The device the layer is relative to.
851
883
* @param xsc Swapchain.
852
-
* @param data All of the pure data bits.
884
+
* @param data All of the pure data bits (not pointers/handles),
885
+
* including what part of the supplied swapchain
886
+
* object to use.
853
887
*/
854
888
xrt_result_t (*layer_equirect1)(struct xrt_compositor *xc,
855
889
struct xrt_device *xdev,
···
863
897
* @param xc Self pointer
864
898
* @param xdev The device the layer is relative to.
865
899
* @param xsc Swapchain.
866
-
* @param data All of the pure data bits.
900
+
* @param data All of the pure data bits (not pointers/handles),
901
+
* including what part of the supplied swapchain
902
+
* object to use.
867
903
*/
868
904
xrt_result_t (*layer_equirect2)(struct xrt_compositor *xc,
869
905
struct xrt_device *xdev,
···
871
907
const struct xrt_layer_data *data);
872
908
873
909
/*!
874
-
* Commits all of the submitted layers, it's from this on that the
875
-
* compositor will use the layers.
910
+
* @brief Commits all of the submitted layers.
911
+
*
912
+
* Only after this call will the compositor actually use the layers.
876
913
*/
877
914
xrt_result_t (*layer_commit)(struct xrt_compositor *xc,
878
915
int64_t frame_id,
···
882
919
* Teardown the compositor.
883
920
*
884
921
* The state tracker must have made sure that no frames or sessions are
885
-
* currently pending. See discard_frame, end_frame, end_session.
922
+
* currently pending.
923
+
*
924
+
* @see xrt_compositor::discard_frame or xrt_compositor::end_frame for a pending frame
925
+
* @see xrt_compositor::end_session for an open session.
886
926
*/
887
927
void (*destroy)(struct xrt_compositor *xc);
888
928
};