matrixfurry.com / monado
The open source OpenXR runtime
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

c/render: Doc improvements

Part-of: <https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2380>

Rylie Pavlik 5a277c8e 1667b416

+111 -61
+111 -61
src/xrt/compositor/render/render_interface.h
··· 697 697 */ 698 698 699 699 /*! 700 - * A render pass while not depending on a @p VkFramebuffer does depend on the 700 + * A render pass, while not depending on a @p VkFramebuffer, does depend on the 701 701 * format of the target image(s), and other options for the render pass. These 702 702 * are used to create a @p VkRenderPass, all @p VkFramebuffer(s) and 703 703 * @p VkPipeline depends on the @p VkRenderPass so hang off this struct. ··· 824 824 */ 825 825 826 826 /*! 827 - * A rendering is used to create command buffers needed to do one frame of 828 - * compositor rendering, it holds onto resources used by the command buffer. 827 + * The low-level resources and operations to perform layer squashing and/or 828 + * mesh distortion for a single frame using graphics shaders. 829 + * 830 + * It uses a two-stage process to render a frame. This means 831 + * consumers iterate layers (or other operations) **twice**, within each target and view. 832 + * There is a preparation stage, where the uniform buffer is sub-allocated and written. 833 + * This must be completed for all layers before the actual draw stage begins. 834 + * The second stage is recording the draw commands into a command buffer. 835 + * 836 + * You must make equivalent calls in the same order between the two stages. The second stage 837 + * additionally has @ref render_gfx_begin_target, @ref render_gfx_end_target, 838 + * @ref render_gfx_begin_view, and @ref render_gfx_end_view lacked by the first stage, 839 + * but if you exclude those functions, the others must line up. 840 + * 841 + * Furthermore, the struct needs to be kept alive until the work has been waited on, 842 + * or you get validation warnings. Either wait on the `VkFence` for the submit, or call 843 + * `vkDeviceWaitIdle`/`vkQueueWaitIdle` on the device/queue. 829 844 * 830 845 * @see comp_render_gfx 831 846 */ ··· 837 852 //! Shared buffer that we sub-allocate UBOs from. 838 853 struct render_sub_alloc_tracker ubo_tracker; 839 854 840 - //! The current target we are rendering too, can change during command building. 855 + //! The current target we are rendering to, can change during command building. 841 856 struct render_gfx_target_resources *rtr; 842 857 }; 843 858 ··· 883 898 884 899 /*! 885 900 * UBO data that is sent to the mesh shaders. 901 + * 902 + * @relates render_gfx 886 903 */ 887 904 struct render_gfx_mesh_ubo_data 888 905 { ··· 896 913 897 914 /*! 898 915 * UBO data that is sent to the layer cylinder shader. 916 + * 917 + * @relates render_gfx 899 918 */ 900 919 struct render_gfx_layer_cylinder_data 901 920 { ··· 909 928 910 929 /*! 911 930 * UBO data that is sent to the layer equirect2 shader. 931 + * 932 + * @relates render_gfx 912 933 */ 913 934 struct render_gfx_layer_equirect2_data 914 935 { ··· 926 947 927 948 /*! 928 949 * UBO data that is sent to the layer projection shader. 950 + * 951 + * @relates render_gfx 929 952 */ 930 953 struct render_gfx_layer_projection_data 931 954 { ··· 936 959 937 960 /*! 938 961 * UBO data that is sent to the layer quad shader. 962 + * 963 + * @relates render_gfx 939 964 */ 940 965 struct render_gfx_layer_quad_data 941 966 { ··· 943 968 struct xrt_matrix_4x4 mvp; 944 969 }; 945 970 946 - 947 971 /*! 948 - * @name Drawing functions 972 + * @name Preparation functions - first stage 949 973 * @{ 950 974 */ 951 975 952 976 /*! 953 - * This function allocates everything to start a single rendering. This is the 954 - * first function you call when you start rendering, you follow up with a call 955 - * to render_gfx_begin_view. 956 - * 957 - * @public @memberof render_gfx 958 - */ 959 - bool 960 - render_gfx_begin_target(struct render_gfx *render, 961 - struct render_gfx_target_resources *rtr, 962 - const VkClearColorValue *color); 963 - 964 - /*! 965 - * @public @memberof render_gfx 966 - */ 967 - void 968 - render_gfx_end_target(struct render_gfx *render); 969 - 970 - /*! 971 - * @public @memberof render_gfx 972 - */ 973 - void 974 - render_gfx_begin_view(struct render_gfx *render, uint32_t view, const struct render_viewport_data *viewport_data); 975 - 976 - /*! 977 - * @public @memberof render_gfx 978 - */ 979 - void 980 - render_gfx_end_view(struct render_gfx *render); 981 - 982 - /*! 983 977 * Allocate needed resources for one mesh shader dispatch, will also update the 984 978 * descriptor set, UBO will be filled out with the given @p data argument. 985 979 * ··· 995 989 VkSampler src_sampler, 996 990 VkImageView src_image_view, 997 991 VkDescriptorSet *out_descriptor_set); 998 - 999 - /*! 1000 - * Dispatch one mesh shader instance, using the give @p mesh_index as source for 1001 - * mesh geometry, timewarp selectable via @p do_timewarp. 1002 - * 1003 - * @public @memberof render_gfx 1004 - */ 1005 - void 1006 - render_gfx_mesh_draw(struct render_gfx *render, uint32_t mesh_index, VkDescriptorSet descriptor_set, bool do_timewarp); 1007 992 1008 993 /*! 1009 994 * Allocate and write a UBO and descriptor_set to be used for cylinder layer ··· 1057 1042 VkImageView src_image_view, 1058 1043 VkDescriptorSet *out_descriptor_set); 1059 1044 1045 + 1060 1046 /*! 1061 - * Dispatch a cylinder layer shader into the current target and view, 1062 - * allocate @p descriptor_set and ubo with 1063 - * @ref render_gfx_layer_cylinder_alloc_and_write. 1047 + * @} 1048 + */ 1049 + 1050 + /*! 1051 + * @name Drawing functions - second stage 1052 + * @{ 1053 + */ 1054 + 1055 + /*! 1056 + * This function allocates everything to start a single rendering. This is the 1057 + * first function you call when you start the drawiing stage, you follow up with a call 1058 + * to @ref render_gfx_begin_view. 1059 + * 1060 + * @public @memberof render_gfx 1061 + */ 1062 + bool 1063 + render_gfx_begin_target(struct render_gfx *render, 1064 + struct render_gfx_target_resources *rtr, 1065 + const VkClearColorValue *color); 1066 + 1067 + /*! 1068 + * @pre successful @ref render_gfx_begin_target call, 1069 + * no @ref render_gfx_begin_view without matching @ref render_gfx_end_view 1070 + * @public @memberof render_gfx 1071 + */ 1072 + void 1073 + render_gfx_end_target(struct render_gfx *render); 1074 + 1075 + /*! 1076 + * @pre successful @ref render_gfx_begin_target call 1077 + * @public @memberof render_gfx 1078 + */ 1079 + void 1080 + render_gfx_begin_view(struct render_gfx *render, uint32_t view, const struct render_viewport_data *viewport_data); 1081 + 1082 + /*! 1083 + * @pre successful @ref render_gfx_begin_view call without a matching call to this function 1084 + * @public @memberof render_gfx 1085 + */ 1086 + void 1087 + render_gfx_end_view(struct render_gfx *render); 1088 + 1089 + /*! 1090 + * Dispatch one mesh shader instance, using the give @p mesh_index as source for 1091 + * mesh geometry, timewarp selectable via @p do_timewarp. 1092 + * 1093 + * Must have successfully called @ref render_gfx_mesh_alloc_and_write 1094 + * before @ref render_gfx_begin_target to allocate @p descriptor_set and UBO. 1095 + * 1096 + * @pre successful @ref render_gfx_mesh_alloc_and_write call, successful @ref render_gfx_begin_view call 1097 + * @public @memberof render_gfx 1098 + */ 1099 + void 1100 + render_gfx_mesh_draw(struct render_gfx *render, uint32_t mesh_index, VkDescriptorSet descriptor_set, bool do_timewarp); 1101 + 1102 + /*! 1103 + * Dispatch a cylinder layer shader into the current target and view. 1104 + * 1105 + * Must have successfully called @ref render_gfx_layer_cylinder_alloc_and_write 1106 + * before @ref render_gfx_begin_target to allocate @p descriptor_set and UBO. 1064 1107 * 1065 1108 * @public @memberof render_gfx 1066 1109 */ ··· 1068 1111 render_gfx_layer_cylinder(struct render_gfx *render, bool premultiplied_alpha, VkDescriptorSet descriptor_set); 1069 1112 1070 1113 /*! 1071 - * Dispatch a equirect2 layer shader into the current target and view, 1072 - * allocate @p descriptor_set and ubo with 1073 - * @ref render_gfx_layer_equirect2_alloc_and_write. 1114 + * Dispatch a equirect2 layer shader into the current target and view. 1115 + * 1116 + * Must have successfully called @ref render_gfx_layer_equirect2_alloc_and_write 1117 + * before @ref render_gfx_begin_target to allocate @p descriptor_set and UBO. 1074 1118 * 1075 1119 * @public @memberof render_gfx 1076 1120 */ ··· 1078 1122 render_gfx_layer_equirect2(struct render_gfx *render, bool premultiplied_alpha, VkDescriptorSet descriptor_set); 1079 1123 1080 1124 /*! 1081 - * Dispatch a projection layer shader into the current target and view, 1082 - * allocate @p descriptor_set and ubo with 1083 - * @ref render_gfx_layer_projection_alloc_and_write. 1125 + * Dispatch a projection layer shader into the current target and view. 1126 + * 1127 + * Must have successfully called @ref render_gfx_layer_projection_alloc_and_write 1128 + * before @ref render_gfx_begin_target to allocate @p descriptor_set and UBO. 1084 1129 * 1085 1130 * @public @memberof render_gfx 1086 1131 */ ··· 1088 1133 render_gfx_layer_projection(struct render_gfx *render, bool premultiplied_alpha, VkDescriptorSet descriptor_set); 1089 1134 1090 1135 /*! 1091 - * Dispatch a quad layer shader into the current target and view, allocate 1092 - * @p descriptor_set and ubo with @ref render_gfx_layer_quad_alloc_and_write. 1136 + * Dispatch a quad layer shader into the current target and view. 1137 + * 1138 + * Must have successfully called @ref render_gfx_layer_quad_alloc_and_write 1139 + * before @ref render_gfx_begin_target to allocate @p descriptor_set and UBO. 1093 1140 * 1094 1141 * @public @memberof render_gfx 1095 1142 */ ··· 1108 1155 */ 1109 1156 1110 1157 /*! 1111 - * A compute rendering is used to create command buffers needed to do one frame 1112 - * of compositor rendering using compute shaders, it holds onto resources used 1113 - * by the command buffer. 1158 + * The semi-low level resources and operations required to squash layers and/or 1159 + * apply distortion for a single frame using compute shaders. 1160 + * 1161 + * Unlike @ref render_gfx, this is a single stage process, and you pass all layers at a single time. 1114 1162 * 1115 1163 * @see comp_render_cs 1116 1164 */ ··· 1132 1180 1133 1181 /*! 1134 1182 * Push data that is sent to the blit shader. 1183 + * 1184 + * @relates render_compute 1135 1185 */ 1136 1186 struct render_compute_blit_push_data 1137 1187 { ··· 1142 1192 /*! 1143 1193 * UBO data that is sent to the compute layer shaders. 1144 1194 * 1145 - * Used in @ref render_compute 1195 + * @relates render_compute 1146 1196 */ 1147 1197 struct render_compute_layer_ubo_data 1148 1198 { ··· 1237 1287 /*! 1238 1288 * UBO data that is sent to the compute distortion shaders. 1239 1289 * 1240 - * Used in @ref render_compute 1290 + * @relates render_compute 1241 1291 */ 1242 1292 struct render_compute_distortion_ubo_data 1243 1293 {