Merge branch 'draw-viewport-data' into eevee-rewrite

# Conflicts:
#	release/scripts/startup/bl_ui/properties_data_camera.py
#	source/blender/blenkernel/BKE_camera.h
#	source/blender/blenkernel/BKE_node.h
#	source/blender/blenkernel/intern/camera.c
#	source/blender/blenlib/BLI_float2.hh
#	source/blender/blenlib/BLI_float3.hh
#	source/blender/blenlib/BLI_float4.hh
#	source/blender/blenlib/BLI_math_geom.h
#	source/blender/blenlib/intern/math_geom.c
#	source/blender/draw/CMakeLists.txt
#	source/blender/draw/engines/basic/basic_engine.c
#	source/blender/draw/engines/eevee/eevee_cryptomatte.c
#	source/blender/draw/engines/eevee/eevee_effects.c
#	source/blender/draw/engines/eevee/eevee_engine.c
#	source/blender/draw/engines/eevee/eevee_lightcache.c
#	source/blender/draw/engines/eevee/eevee_lightcache.h
#	source/blender/draw/engines/eevee/eevee_lightprobes.c
#	source/blender/draw/engines/eevee/eevee_lights.c
#	source/blender/draw/engines/eevee/eevee_materials.c
#	source/blender/draw/engines/eevee/eevee_motion_blur.c
#	source/blender/draw/engines/eevee/eevee_occlusion.c
#	source/blender/draw/engines/eevee/eevee_private.h
#	source/blender/draw/engines/eevee/eevee_render.c
#	source/blender/draw/engines/eevee/eevee_renderpasses.c
#	source/blender/draw/engines/eevee/eevee_sampling.c
#	source/blender/draw/engines/eevee/eevee_screen_raytrace.c
#	source/blender/draw/engines/eevee/eevee_shaders.c
#	source/blender/draw/engines/eevee/eevee_shadows.c
#	source/blender/draw/engines/eevee/eevee_shadows_cube.c
#	source/blender/draw/engines/eevee/eevee_temporal_sampling.c
#	source/blender/draw/engines/eevee/shaders/ambient_occlusion_lib.glsl
#	source/blender/draw/engines/eevee/shaders/closure_eval_lib.glsl
#	source/blender/draw/engines/eevee/shaders/common_utiltex_lib.glsl
#	source/blender/draw/engines/eevee/shaders/effect_dof_bokeh_frag.glsl
#	source/blender/draw/engines/eevee/shaders/effect_dof_gather_frag.glsl
#	source/blender/draw/engines/eevee/shaders/effect_dof_reduce_frag.glsl
#	source/blender/draw/engines/eevee/shaders/effect_reflection_resolve_frag.glsl
#	source/blender/draw/engines/eevee/shaders/effect_temporal_aa.glsl
#	source/blender/draw/engines/eevee/shaders/random_lib.glsl
#	source/blender/draw/engines/eevee/shaders/shadow_vert.glsl
#	source/blender/draw/engines/eevee/shaders/surface_lib.glsl
#	source/blender/draw/engines/eevee/shaders/surface_vert.glsl
#	source/blender/draw/engines/eevee/shaders/volumetric_lib.glsl
#	source/blender/draw/engines/external/external_engine.c
#	source/blender/draw/engines/gpencil/gpencil_engine.c
#	source/blender/draw/engines/image/image_engine.c
#	source/blender/draw/engines/overlay/overlay_engine.c
#	source/blender/draw/engines/select/select_engine.c
#	source/blender/draw/engines/workbench/shaders/workbench_volume_frag.glsl
#	source/blender/draw/engines/workbench/shaders/workbench_volume_vert.glsl
#	source/blender/draw/engines/workbench/workbench_engine.c
#	source/blender/draw/engines/workbench/workbench_shader.c
#	source/blender/draw/intern/DRW_render.h
#	source/blender/draw/intern/draw_debug.h
#	source/blender/draw/intern/draw_manager_data.c
#	source/blender/draw/intern/draw_manager_exec.c
#	source/blender/draw/intern/draw_view_data.h
#	source/blender/gpu/CMakeLists.txt
#	source/blender/gpu/GPU_material.h
#	source/blender/gpu/GPU_shader.h
#	source/blender/gpu/GPU_state.h
#	source/blender/gpu/GPU_vertex_buffer.h
#	source/blender/gpu/intern/gpu_codegen.c
#	source/blender/gpu/intern/gpu_material.c
#	source/blender/gpu/intern/gpu_material_library.h
#	source/blender/gpu/intern/gpu_node_graph.c
#	source/blender/gpu/intern/gpu_texture_private.hh
#	source/blender/gpu/intern/gpu_vertex_buffer.cc
#	source/blender/gpu/opengl/gl_shader.cc
#	source/blender/gpu/shaders/gpu_shader_common_obinfos_lib.glsl
#	source/blender/gpu/shaders/material/gpu_shader_material_shader_to_rgba.glsl
#	source/blender/nodes/shader/node_shader_tree.cc
#	source/blender/nodes/shader/nodes/node_shader_background.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_anisotropic.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_diffuse.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_glass.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_glossy.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_hair.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_hair_principled.c
#	source/blender/nodes/shader/nodes/node_shader_bsdf_principled.c
#	source/blender/nodes/shader/nodes/node_shader_bsdf_refraction.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_toon.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_translucent.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_transparent.cc
#	source/blender/nodes/shader/nodes/node_shader_bsdf_velvet.cc
#	source/blender/nodes/shader/nodes/node_shader_eevee_specular.cc
#	source/blender/nodes/shader/nodes/node_shader_emission.cc
#	source/blender/nodes/shader/nodes/node_shader_holdout.cc
#	source/blender/nodes/shader/nodes/node_shader_output_material.cc
#	source/blender/nodes/shader/nodes/node_shader_subsurface_scattering.c
#	source/blender/nodes/shader/nodes/node_shader_tex_coord.cc
#	source/blender/nodes/shader/nodes/node_shader_vector_transform.cc
#	source/blender/nodes/shader/nodes/node_shader_volume_absorption.cc
#	source/blender/nodes/shader/nodes/node_shader_volume_principled.cc
#	source/blender/nodes/shader/nodes/node_shader_volume_scatter.cc
#	source/blender/render/RE_pipeline.h
#	source/blender/render/intern/initrender.c

1 files changed, 30 insertions, 3 deletions

diff --git a/source/blender/gpu/GPU_select.h b/source/blender/gpu/GPU_select.h
index d28363253b1..c02af763311 100644
--- a/source/blender/gpu/GPU_select.h
+++ b/source/blender/gpu/GPU_select.h
@@ -31,7 +31,7 @@ extern "C" {
 
 struct rcti;
 
-/* flags for mode of operation */
+/** Flags for mode of operation. */
 enum {
   GPU_SELECT_ALL = 1,
   /* gpu_select_query */
@@ -42,21 +42,48 @@ enum {
   GPU_SELECT_PICK_NEAREST = 5,
 };
 
+/**
+ * Initialize and provide buffer for results.
+ */
 void GPU_select_begin(
     unsigned int *buffer, unsigned int bufsize, const struct rcti *input, char mode, int oldhits);
+/**
+ * Loads a new selection id and ends previous query, if any.
+ * In second pass of selection it also returns
+ * if id has been hit on the first pass already.
+ * Thus we can skip drawing un-hit objects.
+ *
+ * \warning We rely on the order of object rendering on passes to be the same for this to work.
+ */
 bool GPU_select_load_id(unsigned int id);
 void GPU_select_finalize(void);
+/**
+ * Cleanup and flush selection results to buffer.
+ * Return number of hits and hits in buffer.
+ * if \a dopass is true, we will do a second pass with occlusion queries to get the closest hit.
+ */
 unsigned int GPU_select_end(void);
 
-/* cache selection region */
+/* Cache selection region. */
+
 bool GPU_select_is_cached(void);
 void GPU_select_cache_begin(void);
 void GPU_select_cache_load_id(void);
 void GPU_select_cache_end(void);
 
-/* utilities */
+/* Utilities. */
+
+/**
+ * Helper function, nothing special but avoids doing inline since hits aren't sorted by depth
+ * and purpose of 4x buffer indices isn't so clear.
+ *
+ * Note that comparing depth as uint is fine.
+ */
 const uint *GPU_select_buffer_near(const uint *buffer, int hits);
 uint GPU_select_buffer_remove_by_id(uint *buffer, int hits, uint select_id);
+/**
+ * Part of the solution copied from `rect_subregion_stride_calc`.
+ */
 void GPU_select_buffer_stride_realign(const struct rcti *src, const struct rcti *dst, uint *r_buf);
 
 #ifdef __cplusplus