Merge branch 'master' into soc-2021-uv-edge-select-supportsoc-2021-uv-edge-select-support

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