summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKeith Whitwell <keith@tungstengraphics.com>2008-02-27 13:06:18 +0000
committerKeith Whitwell <keith@tungstengraphics.com>2008-03-03 17:50:09 +0100
commitf4e91c3432eaf653757193a8a1ac438372ea64a6 (patch)
tree77e2a249bdcbd68e49fd38436a20e80bc068c760
parenta9c40f833ead8459788b86603c7f2b94632b1109 (diff)
gallium: document user_buffer_create a little
-rw-r--r--src/gallium/include/pipe/p_winsys.h31
1 files changed, 27 insertions, 4 deletions
diff --git a/src/gallium/include/pipe/p_winsys.h b/src/gallium/include/pipe/p_winsys.h
index e784c92491..1383bd0544 100644
--- a/src/gallium/include/pipe/p_winsys.h
+++ b/src/gallium/include/pipe/p_winsys.h
@@ -104,13 +104,36 @@ struct pipe_winsys
* usage is a bitmask of PIPE_BUFFER_USAGE_PIXEL/VERTEX/INDEX/CONSTANT. This
* usage argument is only an optimization hint, not a guarantee, therefore
* proper behavior must be observed in all circumstances.
+ *
+ * alignment indicates the client's alignment requirements, eg for
+ * SSE instructions.
*/
struct pipe_buffer *(*buffer_create)( struct pipe_winsys *sws,
- unsigned alignment,
- unsigned usage,
- unsigned size );
+ unsigned alignment,
+ unsigned usage,
+ unsigned size );
- /** Create a buffer that wraps user-space data */
+ /**
+ * Create a buffer that wraps user-space data.
+ *
+ * Effectively this schedules a delayed call to buffer_create
+ * followed by an upload of the data at *some point in the future*,
+ * or perhaps never. Basically the allocate/upload is delayed
+ * until the buffer is actually passed to hardware.
+ *
+ * The intention is to provide a quick way to turn regular data
+ * into a buffer, and secondly to avoid a copy operation if that
+ * data subsequently turns out to be only accessed by the CPU.
+ *
+ * Common example is OpenGL vertex buffers that are subsequently
+ * processed either by software TNL in the driver or by passing to
+ * hardware.
+ *
+ * XXX: What happens if the delayed call to buffer_create() fails?
+ *
+ * Note that ptr may be accessed at any time upto the time when the
+ * buffer is destroyed, so the data must not be freed before then.
+ */
struct pipe_buffer *(*user_buffer_create)(struct pipe_winsys *sws,
void *ptr,
unsigned bytes);