cogl/cogl-indices.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2010 Intel Corporation.
   7  *
   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.
  12  *
  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.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  *
  21  *
  22  *
  23  * Authors:
  24  *   Robert Bragg <robert@linux.intel.com>
  25  */
  26
  27 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  28 #error "Only <cogl/cogl.h> can be included directly."
  29 #endif
  30
  31 #ifndef __COGL_INDICES_H__
  32 #define __COGL_INDICES_H__
  33
  34 /* We forward declare the CoglIndices type here to avoid some circular
  35  * dependency issues with the following headers.
  36  */
  37 typedef struct _CoglIndices CoglIndices;
  38
  39 #include <cogl/cogl-index-buffer.h>
  40
  41 G_BEGIN_DECLS
  42
  43 /**
  44  * SECTION:cogl-index-range
  45  * @short_description: Fuctions for declaring a range of vertex indices
  46  *   stored in a #CoglIndexBuffer.
  47  *
  48  * Indices allow you to avoid duplicating vertices in your vertex data
  49  * by virtualizing your data and instead providing a sequence of index
  50  * values that tell the GPU which data should be used for each vertex.
  51  *
  52  * If the GPU is given a squence of indices it doesn't simply walk
  53  * through each vertex of your data in order it will instead walk
  54  * through the indices which can provide random access to the
  55  * underlying data.
  56  *
  57  * Since it's very common to have duplicate vertices when describing a
  58  * shape as a list of triangles it can often be a significant space
  59  * saving to describe geometry using indices. Reducing the size of
  60  * your models can make it cheaper to map them into the GPU by
  61  * reducing the demand on memory bandwidth and may help to make better
  62  * use of your GPUs internal vertex caching.
  63  *
  64  * For example, to describe a quadrilateral as 2 triangles for the GPU
  65  * you could either provide data with 6 vertices or instead with
  66  * indices you can provide vertex data for just 4 vertices and an
  67  * index buffer that specfies the 6 vertices by indexing the shared
  68  * vertices multiple times.
  69  *
  70  * |[
  71  *   CoglVertex2f quad_vertices[] = {
  72  *     {x0, y0}, //0 = top left
  73  *     {x1, y1}, //1 = bottom left
  74  *     {x2, y2}, //2 = bottom right
  75  *     {x3, y3}, //3 = top right
  76  *   };
  77  *   //tell the gpu how to interpret the quad as 2 triangles...
  78  *   unsigned char indices[] = {0, 1, 2, 0, 2, 3};
  79  * ]|
  80  *
  81  * Even in the above illustration we see a saving of 10bytes for one
  82  * quad compared to having data for 6 vertices and no indices but if
  83  * you need to draw 100s or 1000s of quads then its really quite
  84  * significant.
  85  *
  86  * Something else to consider is that often indices can be defined
  87  * once and remain static while the vertex data may change for
  88  * animations perhaps. That means you may be able to ignore the
  89  * negligable cost of mapping your indices into the GPU if they don't
  90  * ever change.
  91  *
  92  * The above illustration is actually a good example of static indices
  93  * because it's really common that developers have quad mesh data that
  94  * they need to display and we know exactly what that indices array
  95  * needs to look like depending on the number of quads that need to be
  96  * drawn. It doesn't matter how the quads might be animated and
  97  * changed the indices will remain the same. Cogl even has a utility
  98  * (cogl_get_rectangle_indices()) to get access to re-useable indices
  99  * for drawing quads as above.
 100  */
 101
 102 CoglIndices *
 103 cogl_indices_new (CoglContext *context,
 104                   CoglIndicesType type,
 105                   const void *indices_data,
 106                   int n_indices);
 107
 108 CoglIndices *
 109 cogl_indices_new_for_buffer (CoglIndicesType type,
 110                              CoglIndexBuffer *buffer,
 111                              gsize offset);
 112
 113 CoglIndexBuffer *
 114 cogl_indices_get_buffer (CoglIndices *indices);
 115
 116 CoglIndicesType
 117 cogl_indices_get_type (CoglIndices *indices);
 118
 119 gsize
 120 cogl_indices_get_offset (CoglIndices *indices);
 121
 122 void
 123 cogl_indices_set_offset (CoglIndices *indices,
 124                          gsize offset);
 125
 126 CoglIndices *
 127 cogl_get_rectangle_indices (CoglContext *context, int n_rectangles);
 128
 129 /**
 130  * cogl_is_indices:
 131  * @object: A #CoglObject pointer
 132  *
 133  * Gets whether the given object references a #CoglIndices.
 134  *
 135  * Return value: %TRUE if the object references a #CoglIndices
 136  *   and %FALSE otherwise.
 137  * Since: 1.10
 138  * Stability: unstable
 139  */
 140 gboolean
 141 cogl_is_indices (void *object);
 142
 143 G_END_DECLS
 144
 145 #endif /* __COGL_INDICES_H__ */
 146