4
* An object oriented GL/GLES Abstraction/Utility Layer
6
* Copyright (C) 2008,2009 Intel Corporation.
8
* This library is free software; you can redistribute it and/or
9
* modify it under the terms of the GNU Lesser General Public
10
* License as published by the Free Software Foundation; either
11
* version 2 of the License, or (at your option) any later version.
13
* This library is distributed in the hope that it will be useful,
14
* but WITHOUT ANY WARRANTY; without even the implied warranty of
15
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16
* Lesser General Public License for more details.
18
* You should have received a copy of the GNU Lesser General Public
19
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
24
* Robert Bragg <robert@linux.intel.com>
27
#if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
28
#error "Only <cogl/cogl.h> can be included directly."
31
#ifndef __COGL_VERTEX_BUFFER_H__
32
#define __COGL_VERTEX_BUFFER_H__
35
#include <cogl/cogl-types.h>
40
* SECTION:cogl-vertex-buffer
41
* @short_description: An API for submitting extensible arrays of vertex
42
* attributes to be mapped into the GPU for fast drawing.
44
* For example to describe a textured triangle, you could create a new cogl
45
* vertex buffer with 3 vertices, and then you might add 2 attributes for each
49
* a "gl_Position" describing the (x,y,z) position for each vertex.
52
* a "gl_MultiTexCoord0" describing the (tx,ty) texture coordinates for each
57
* The Vertex Buffer API is designed to be a fairly raw mechanism for
58
* developers to be able to submit geometry to Cogl in a format that can be
59
* directly consumed by an OpenGL driver and mapped into your GPU for fast
60
* re-use. It is designed to avoid repeated validation of the attributes by the
61
* driver; to minimize transport costs (e.g. considering indirect GLX
62
* use-cases) and to potentially avoid repeated format conversions when
63
* attributes are supplied in a format that is not natively supported by the
66
* Although this API does allow you to modify attributes after they have been
67
* submitted to the GPU you should be aware that modification is not that
68
* cheap, since it implies validating the new data and potentially the
69
* OpenGL driver will need to reformat it for the GPU.
71
* If at all possible think of tricks that let you re-use static attributes,
72
* and if you do need to repeatedly update attributes (e.g. for some kind of
73
* morphing geometry) then only update and re-submit the specific attributes
78
* cogl_vertex_buffer_new:
79
* @n_vertices: The number of vertices that your attributes will correspond to.
81
* Creates a new vertex buffer that you can use to add attributes.
83
* Return value: a new #CoglHandle
86
cogl_vertex_buffer_new (unsigned int n_vertices);
89
* cogl_vertex_buffer_get_n_vertices:
90
* @handle: A vertex buffer handle
92
* Retrieves the number of vertices that @handle represents
94
* Return value: the number of vertices
97
cogl_vertex_buffer_get_n_vertices (CoglHandle handle);
101
* @COGL_ATTRIBUTE_TYPE_BYTE: Data is the same size of a byte
102
* @COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE: Data is the same size of an
104
* @COGL_ATTRIBUTE_TYPE_SHORT: Data is the same size of a short integer
105
* @COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT: Data is the same size of
106
* an unsigned short integer
107
* @COGL_ATTRIBUTE_TYPE_FLOAT: Data is the same size of a float
109
* Data types for the components of cogl_vertex_buffer_add()
114
COGL_ATTRIBUTE_TYPE_BYTE = GL_BYTE,
115
COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE = GL_UNSIGNED_BYTE,
116
COGL_ATTRIBUTE_TYPE_SHORT = GL_SHORT,
117
COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT = GL_UNSIGNED_SHORT,
118
COGL_ATTRIBUTE_TYPE_FLOAT = GL_FLOAT
122
* cogl_vertex_buffer_add:
123
* @handle: A vertex buffer handle
124
* @attribute_name: The name of your attribute. It should be a valid GLSL
125
* variable name and standard attribute types must use one of following
126
* built-in names: (Note: they correspond to the built-in names of GLSL)
128
* <listitem>"gl_Color"</listitem>
129
* <listitem>"gl_Normal"</listitem>
130
* <listitem>"gl_MultiTexCoord0, gl_MultiTexCoord1, ..."</listitem>
131
* <listitem>"gl_Vertex"</listitem>
133
* To support adding multiple variations of the same attribute the name
134
* can have a detail component, E.g. "gl_Color::active" or
135
* "gl_Color::inactive"
136
* @n_components: The number of components per attribute and must be 1, 2,
138
* @type: a #CoglAttributeType specifying the data type of each component.
139
* @normalized: If %TRUE, this specifies that values stored in an integer
140
* format should be mapped into the range [-1.0, 1.0] or [0.0, 1.0]
141
* for unsigned values. If %FALSE they are converted to floats
143
* @stride: This specifies the number of bytes from the start of one attribute
144
* value to the start of the next value (for the same attribute). So, for
145
* example, with a position interleved with color like this:
146
* XYRGBAXYRGBAXYRGBA, then if each letter represents a byte, the
147
* stride for both attributes is 6. The special value 0 means the
148
* values are stored sequentially in memory.
149
* @pointer: This addresses the first attribute in the vertex array. This
150
* must remain valid until you either call cogl_vertex_buffer_submit() or
153
* Adds an attribute to a buffer.
155
* You either can use one of the built-in names such as "gl_Vertex", or
156
* "gl_MultiTexCoord0" to add standard attributes, like positions, colors
157
* and normals, or you can add custom attributes for use in shaders.
159
* The number of vertices declared when calling cogl_vertex_buffer_new()
160
* determines how many attribute values will be read from the supplied
163
* The data for your attribute isn't copied anywhere until you call
164
* cogl_vertex_buffer_submit(), or issue a draw call which automatically
165
* submits pending attribute changes. so the supplied pointer must remain
166
* valid until then. If you are updating an existing attribute (done by
167
* re-adding it) then you still need to re-call cogl_vertex_buffer_submit()
168
* to commit the changes to the GPU. Be carefull to minimize the number
169
* of calls to cogl_vertex_buffer_submit(), though.
171
* <note>If you are interleving attributes it is assumed that each interleaved
172
* attribute starts no farther than +- stride bytes from the other attributes
173
* it is interleved with. I.e. this is ok:
175
* |-0-0-0-0-0-0-0-0-0-0|
179
* |- - - - -0-0-0-0-0-0 0 0 0 0|
181
* (Though you can have multiple groups of interleved attributes)</note>
184
cogl_vertex_buffer_add (CoglHandle handle,
185
const char *attribute_name,
187
CoglAttributeType type,
190
const void *pointer);
193
* cogl_vertex_buffer_delete:
194
* @handle: A vertex buffer handle
195
* @attribute_name: The name of a previously added attribute
197
* Deletes an attribute from a buffer. You will need to call
198
* cogl_vertex_buffer_submit() or issue a draw call to commit this
202
cogl_vertex_buffer_delete (CoglHandle handle,
203
const char *attribute_name);
206
* cogl_vertex_buffer_submit:
207
* @handle: A vertex buffer handle
209
* Submits all the user added attributes to the GPU; once submitted, the
210
* attributes can be used for drawing.
212
* You should aim to minimize calls to this function since it implies
213
* validating your data; it potentially incurs a transport cost (especially if
214
* you are using GLX indirect rendering) and potentially a format conversion
215
* cost if the GPU doesn't natively support any of the given attribute formats.
218
cogl_vertex_buffer_submit (CoglHandle handle);
221
* cogl_vertex_buffer_disable:
222
* @handle: A vertex buffer handle
223
* @attribute_name: The name of the attribute you want to disable
225
* Disables a previosuly added attribute.
227
* Since it can be costly to add and remove new attributes to buffers; to make
228
* individual buffers more reuseable it is possible to enable and disable
229
* attributes before using a buffer for drawing.
231
* You don't need to call cogl_vertex_buffer_submit() after using this
235
cogl_vertex_buffer_disable (CoglHandle handle,
236
const char *attribute_name);
239
* cogl_vertex_buffer_enable:
240
* @handle: A vertex buffer handle
241
* @attribute_name: The name of the attribute you want to enable
243
* Enables a previosuly disabled attribute.
245
* Since it can be costly to add and remove new attributes to buffers; to make
246
* individual buffers more reuseable it is possible to enable and disable
247
* attributes before using a buffer for drawing.
249
* You don't need to call cogl_vertex_buffer_submit() after using this function
252
cogl_vertex_buffer_enable (CoglHandle handle,
253
const char *attribute_name);
257
* @COGL_VERTICES_MODE_POINTS: FIXME, equivalent to %GL_POINTS
258
* @COGL_VERTICES_MODE_LINE_STRIP: FIXME, equivalent to %GL_LINE_STRIP
259
* @COGL_VERTICES_MODE_LINE_LOOP: FIXME, equivalent to %GL_LINE_LOOP
260
* @COGL_VERTICES_MODE_LINES: FIXME, equivalent to %GL_LINES
261
* @COGL_VERTICES_MODE_TRIANGLE_STRIP: FIXME, equivalent to %GL_TRIANGLE_STRIP
262
* @COGL_VERTICES_MODE_TRIANGLE_FAN: FIXME, equivalent to %GL_TRIANGLE_FAN
263
* @COGL_VERTICES_MODE_TRIANGLES: FIXME, equivalent to %GL_TRIANGLES
265
* How vertices passed to cogl_vertex_buffer_draw() and
266
* cogl_vertex_buffer_draw_elements() should be interpreted
271
COGL_VERTICES_MODE_POINTS = GL_POINTS,
272
COGL_VERTICES_MODE_LINE_STRIP = GL_LINE_STRIP,
273
COGL_VERTICES_MODE_LINE_LOOP = GL_LINE_LOOP,
274
COGL_VERTICES_MODE_LINES = GL_LINES,
275
COGL_VERTICES_MODE_TRIANGLE_STRIP = GL_TRIANGLE_STRIP,
276
COGL_VERTICES_MODE_TRIANGLE_FAN = GL_TRIANGLE_FAN,
277
COGL_VERTICES_MODE_TRIANGLES = GL_TRIANGLES
281
* cogl_vertex_buffer_draw:
282
* @handle: A vertex buffer handle
283
* @mode: A #CoglVerticesMode specifying how the vertices should be
285
* @first: Specifies the index of the first vertex you want to draw with
286
* @count: Specifies the number of vertices you want to draw.
288
* Allows you to draw geometry using all or a subset of the
289
* vertices in a vertex buffer.
291
* Any un-submitted attribute changes are automatically submitted before
295
cogl_vertex_buffer_draw (CoglHandle handle,
296
CoglVerticesMode mode,
302
* @COGL_INDICES_TYPE_UNSIGNED_BYTE: Your indices are unsigned bytes
303
* @COGL_INDICES_TYPE_UNSIGNED_SHORT: Your indices are unsigned shorts
304
* @COGL_INDICES_TYPE_UNSIGNED_INT: Your indices are unsigned ints
306
* You should aim to use the smallest data type that gives you enough
307
* range, since it reduces the size of your index array and can help
308
* reduce the demand on memory bandwidth.
310
* Note that %COGL_INDICES_TYPE_UNSIGNED_INT is only supported if the
311
* %COGL_FEATURE_UNSIGNED_INT_INDICES feature is available. This
312
* should always be available on OpenGL but on OpenGL ES it will only
313
* be available if the GL_OES_element_index_uint extension is
317
COGL_INDICES_TYPE_UNSIGNED_BYTE,
318
COGL_INDICES_TYPE_UNSIGNED_SHORT,
319
COGL_INDICES_TYPE_UNSIGNED_INT,
323
* cogl_vertex_buffer_indices_new:
324
* @indices_type: a #CoglIndicesType specifying the data type used for
326
* @indices_array: (array length=indices_len): Specifies the address of
327
* your array of indices
328
* @indices_len: The number of indices in indices_array
330
* Depending on how much geometry you are submitting it can be worthwhile
331
* optimizing the number of redundant vertices you submit. Using an index
332
* array allows you to reference vertices multiple times, for example
333
* during triangle strips.
335
* Return value: A CoglHandle for the indices which you can pass to
336
* cogl_vertex_buffer_draw_elements().
339
cogl_vertex_buffer_indices_new (CoglIndicesType indices_type,
340
const void *indices_array,
344
* cogl_vertex_buffer_indices_get_type:
345
* @handle: An indices handle
347
* Queries back the data type used for the given indices
349
* Returns: The CoglIndicesType used
352
cogl_vertex_buffer_indices_get_type (CoglHandle indices);
355
* cogl_vertex_buffer_draw_elements:
356
* @handle: A vertex buffer handle
357
* @mode: A #CoglVerticesMode specifying how the vertices should be
359
* @indices: A CoglHandle for a set of indices allocated via
360
* cogl_vertex_buffer_indices_new ()
361
* @min_index: Specifies the minimum vertex index contained in indices
362
* @max_index: Specifies the maximum vertex index contained in indices
363
* @indices_offset: An offset into named indices. The offset marks the first
364
* index to use for drawing.
365
* @count: Specifies the number of vertices you want to draw.
367
* This function lets you use an array of indices to specify the vertices
368
* within your vertex buffer that you want to draw. The indices themselves
369
* are created by calling cogl_vertex_buffer_indices_new ()
371
* Any un-submitted attribute changes are automatically submitted before
375
cogl_vertex_buffer_draw_elements (CoglHandle handle,
376
CoglVerticesMode mode,
383
#ifndef COGL_DISABLE_DEPRECATED
386
* cogl_vertex_buffer_ref:
387
* @handle: a @CoglHandle.
389
* Increment the reference count for a vertex buffer
391
* Return value: the @handle.
393
* Deprecated: 1.2: Use cogl_handle_ref() instead
396
cogl_vertex_buffer_ref (CoglHandle handle) G_GNUC_DEPRECATED;
399
* cogl_vertex_buffer_unref:
400
* @handle: a @CoglHandle.
402
* Decrement the reference count for a vertex buffer
404
* Deprecated: 1.2: Use cogl_handle_unref() instead
407
cogl_vertex_buffer_unref (CoglHandle handle) G_GNUC_DEPRECATED;
409
#endif /* COGL_DISABLE_DEPRECATED */
412
* cogl_vertex_buffer_indices_get_for_quads:
413
* @n_indices: the number of indices in the vertex buffer.
415
* Creates a vertex buffer containing the indices needed to draw pairs
416
* of triangles from a list of vertices grouped as quads. There will
417
* be at least @n_indices entries in the buffer (but there may be
420
* The indices will follow this pattern:
422
* 0, 1, 2, 0, 2, 3, 4, 5, 6, 4, 6, 7 ... etc
424
* For example, if you submit vertices for a quad like this:
435
* Then you can request 6 indices to render two triangles like this:
446
* Returns: A %CoglHandle containing the indices. The handled is
447
* owned by Cogl and should not be modified or unref'd.
450
cogl_vertex_buffer_indices_get_for_quads (unsigned int n_indices);
453
* cogl_is_vertex_buffer:
454
* @handle: a #CoglHandle for a vertex buffer object
456
* Checks whether @handle is a Vertex Buffer Object
458
* Return value: %TRUE if the handle is a VBO, and %FALSE
464
cogl_is_vertex_buffer (CoglHandle handle);
468
#endif /* __COGL_VERTEX_BUFFER_H__ */
added
removed
clutter/cogl/cogl/cogl-vertex-buffer.h
