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

1 files changed, 41 insertions, 7 deletions

diff --git a/source/blender/gpu/GPU_vertex_buffer.h b/source/blender/gpu/GPU_vertex_buffer.h
index 2c54016daa7..62a495abfb3 100644
--- a/source/blender/gpu/GPU_vertex_buffer.h
+++ b/source/blender/gpu/GPU_vertex_buffer.h
@@ -79,10 +79,13 @@ GPUVertBuf *GPU_vertbuf_create_with_format_ex(const GPUVertFormat *, GPUUsageTyp
  */
 const void *GPU_vertbuf_read(GPUVertBuf *verts);
 void *GPU_vertbuf_unmap(const GPUVertBuf *verts, const void *mapped_data);
+/** Same as discard but does not free. */
 void GPU_vertbuf_clear(GPUVertBuf *verts);
 void GPU_vertbuf_discard(GPUVertBuf *);
 
-/* Avoid GPUVertBuf datablock being free but not its data. */
+/**
+ * Avoid GPUVertBuf data-block being free but not its data.
+ */
 void GPU_vertbuf_handle_ref_add(GPUVertBuf *verts);
 void GPU_vertbuf_handle_ref_remove(GPUVertBuf *verts);
 
@@ -93,25 +96,42 @@ void GPU_vertbuf_init_with_format_ex(GPUVertBuf *, const GPUVertFormat *, GPUUsa
 
 GPUVertBuf *GPU_vertbuf_duplicate(GPUVertBuf *verts);
 
+/**
+ * Create a new allocation, discarding any existing data.
+ */
 void GPU_vertbuf_data_alloc(GPUVertBuf *, uint v_len);
+/**
+ * Resize buffer keeping existing data.
+ */
 void GPU_vertbuf_data_resize(GPUVertBuf *, uint v_len);
+/**
+ * Set vertex count but does not change allocation.
+ * Only this many verts will be uploaded to the GPU and rendered.
+ * This is useful for streaming data.
+ */
 void GPU_vertbuf_data_len_set(GPUVertBuf *, uint v_len);
 
-/* The most important #set_attr variant is the untyped one. Get it right first.
+/**
+ * The most important #set_attr variant is the untyped one. Get it right first.
  * It takes a void* so the app developer is responsible for matching their app data types
  * to the vertex attribute's type and component count. They're in control of both, so this
- * should not be a problem. */
-
+ * should not be a problem.
+ */
 void GPU_vertbuf_attr_set(GPUVertBuf *, uint a_idx, uint v_idx, const void *data);
 
+/** Fills a whole vertex (all attributes). Data must match packed layout. */
 void GPU_vertbuf_vert_set(GPUVertBuf *verts, uint v_idx, const void *data);
 
-/* Tightly packed, non interleaved input data. */
+/**
+ * Tightly packed, non interleaved input data.
+ */
 void GPU_vertbuf_attr_fill(GPUVertBuf *, uint a_idx, const void *data);
 
 void GPU_vertbuf_attr_fill_stride(GPUVertBuf *, uint a_idx, uint stride, const void *data);
 
-/* For low level access only */
+/**
+ * For low level access only.
+ */
 typedef struct GPUVertBufRaw {
   uint size;
   uint stride;
@@ -138,18 +158,32 @@ GPU_INLINE uint GPU_vertbuf_raw_used(GPUVertBufRaw *a)
 
 void GPU_vertbuf_attr_get_raw_data(GPUVertBuf *, uint a_idx, GPUVertBufRaw *access);
 
+/**
+ * Returns the data buffer and set it to null internally to avoid freeing.
+ * \note Be careful when using this. The data needs to match the expected format.
+ */
 void *GPU_vertbuf_steal_data(GPUVertBuf *verts);
 
+/**
+ * \note Be careful when using this. The data needs to match the expected format.
+ */
 void *GPU_vertbuf_get_data(const GPUVertBuf *verts);
 const GPUVertFormat *GPU_vertbuf_get_format(const GPUVertBuf *verts);
 uint GPU_vertbuf_get_vertex_alloc(const GPUVertBuf *verts);
 uint GPU_vertbuf_get_vertex_len(const GPUVertBuf *verts);
 GPUVertBufStatus GPU_vertbuf_get_status(const GPUVertBuf *verts);
 
+/**
+ * Should be rename to #GPU_vertbuf_data_upload.
+ */
 void GPU_vertbuf_use(GPUVertBuf *);
 void GPU_vertbuf_bind_as_ssbo(struct GPUVertBuf *verts, int binding);
 
-/* XXX do not use. */
+/**
+ * XXX: do not use!
+ * This is just a wrapper for the use of the Hair refine workaround.
+ * To be used with #GPU_vertbuf_use().
+ */
 void GPU_vertbuf_update_sub(GPUVertBuf *verts, uint start, uint len, void *data);
 
 /* Metrics */