cogl/cogl-attribute.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_ATTRIBUTE_H__
  32 #define __COGL_ATTRIBUTE_H__
  33
  34 /* We forward declare the CoglAttribute type here to avoid some circular
  35  * dependency issues with the following headers.
  36  */
  37 typedef struct _CoglAttribute CoglAttribute;
  38
  39 #include <cogl/cogl-attribute-buffer.h>
  40 #include <cogl/cogl-indices.h>
  41
  42 G_BEGIN_DECLS
  43
  44 /**
  45  * SECTION:cogl-attribute
  46  * @short_description: Functions for declaring and drawing vertex
  47  *    attributes
  48  *
  49  * FIXME
  50  */
  51
  52 /**
  53  * cogl_attribute_new:
  54  * @attribute_buffer: The #CoglAttributeBuffer containing the actual
  55  *                    attribute data
  56  * @name: The name of the attribute (used to reference it from GLSL)
  57  * @stride: The number of bytes to jump to get to the next attribute
  58  *          value for the next vertex. (Usually
  59  *          <pre>sizeof (MyVertex)</pre>)
  60  * @offset: The byte offset from the start of @attribute_buffer for
  61  *          the first attribute value. (Usually
  62  *          <pre>offsetof (MyVertex, component0)</pre>
  63  * @components: The number of components (e.g. 4 for an rgba color or
  64  *              3 for and (x,y,z) position)
  65  * @type: FIXME
  66  *
  67  * Describes the layout for a list of vertex attribute values (For
  68  * example, a list of texture coordinates or colors).
  69  *
  70  * The @name is used to access the attribute inside a GLSL vertex
  71  * shader and there are some special names you should use if they are
  72  * applicable:
  73  *  <itemizedlist>
  74  *    <listitem>"cogl_position_in" (used for vertex positions)</listitem>
  75  *    <listitem>"cogl_color_in" (used for vertex colors)</listitem>
  76  *    <listitem>"cogl_tex_coord0_in", "cogl_tex_coord1", ...
  77  * (used for vertex texture coordinates)</listitem>
  78  *    <listitem>"cogl_normal_in" (used for vertex normals)</listitem>
  79  *  </itemizedlist>
  80  *
  81  * The attribute values corresponding to different vertices can either
  82  * be tightly packed or interleaved with other attribute values. For
  83  * example it's common to define a structure for a single vertex like:
  84  * |[
  85  * typedef struct
  86  * {
  87  *   float x, y, z; /<!-- -->* position attribute *<!-- -->/
  88  *   float s, t; /<!-- -->* texture coordinate attribute *<!-- -->/
  89  * } MyVertex;
  90  * ]|
  91  *
  92  * And then create an array of vertex data something like:
  93  * |[
  94  * MyVertex vertices[100] = { .... }
  95  * ]|
  96  *
  97  * In this case, to describe either the position or texture coordinate
  98  * attribute you have to move <pre>sizeof (MyVertex)</pre> bytes to
  99  * move from one vertex to the next.  This is called the attribute
 100  * @stride. If you weren't interleving attributes and you instead had
 101  * a packed array of float x, y pairs then the attribute stride would
 102  * be <pre>(2 * sizeof (float))</pre>. So the @stride is the number of
 103  * bytes to move to find the attribute value of the next vertex.
 104  *
 105  * Normally a list of attributes starts at the beginning of an array.
 106  * So for the <pre>MyVertex</pre> example above the @offset is the
 107  * offset inside the <pre>MyVertex</pre> structure to the first
 108  * component of the attribute. For the texture coordinate attribute
 109  * the offset would be <pre>offsetof (MyVertex, s)</pre> or instead of
 110  * using the offsetof macro you could use <pre>sizeof (float) * 3</pre>.
 111  * If you've divided your @array into blocks of non-interleved
 112  * attributes then you will need to calculate the @offset as the
 113  * number of bytes in blocks preceding the attribute you're
 114  * describing.
 115  *
 116  * An attribute often has more than one component. For example a color
 117  * is often comprised of 4 red, green, blue and alpha @components, and a
 118  * position may be comprised of 2 x and y @components. You should aim
 119  * to keep the number of components to a minimum as more components
 120  * means more data needs to be mapped into the GPU which can be a
 121  * bottlneck when dealing with a large number of vertices.
 122  *
 123  * Finally you need to specify the component data type. Here you
 124  * should aim to use the smallest type that meets your precision
 125  * requirements. Again the larger the type then more data needs to be
 126  * mapped into the GPU which can be a bottlneck when dealing with
 127  * a large number of vertices.
 128  *
 129  * Returns: A newly allocated #CoglAttribute describing the
 130  *          layout for a list of attribute values stored in @array.
 131  *
 132  * Since: 1.4
 133  * Stability: Unstable
 134  */
 135 /* XXX: look for a precedent to see if the stride/offset args should
 136  * have a different order. */
 137 CoglAttribute *
 138 cogl_attribute_new (CoglAttributeBuffer *attribute_buffer,
 139                     const char *name,
 140                     gsize stride,
 141                     gsize offset,
 142                     int components,
 143                     CoglAttributeType type);
 144
 145 /**
 146  * cogl_attribute_set_normalized:
 147  * @attribute: A #CoglAttribute
 148  * @normalized: The new value for the normalized property.
 149  *
 150  * Sets whether fixed point attribute types are mapped to the range
 151  * 0→1. For example when this property is TRUE and a
 152  * %COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE type is used then the value 255
 153  * will be mapped to 1.0.
 154  *
 155  * The default value of this property depends on the name of the
 156  * attribute. For the builtin properties cogl_color_in and
 157  * cogl_normal_in it will default to TRUE and for all other names it
 158  * will default to FALSE.
 159  *
 160  * Stability: unstable
 161  * Since: 1.10
 162  */
 163 void
 164 cogl_attribute_set_normalized (CoglAttribute *attribute,
 165                                gboolean normalized);
 166
 167 /**
 168  * cogl_attribute_get_normalized:
 169  * @attribute: A #CoglAttribute
 170  *
 171  * Return value: the value of the normalized property set with
 172  * cogl_attribute_set_normalized().
 173  *
 174  * Stability: unstable
 175  * Since: 1.10
 176  */
 177 gboolean
 178 cogl_attribute_get_normalized (CoglAttribute *attribute);
 179
 180 /**
 181  * cogl_attribute_get_buffer:
 182  * @attribute: A #CoglAttribute
 183  *
 184  * Return value: the #CoglAttributeBuffer that was set with
 185  * cogl_attribute_set_buffer() or cogl_attribute_new().
 186  *
 187  * Stability: unstable
 188  * Since: 1.10
 189  */
 190 CoglAttributeBuffer *
 191 cogl_attribute_get_buffer (CoglAttribute *attribute);
 192
 193 /**
 194  * cogl_attribute_set_buffer:
 195  * @attribute: A #CoglAttribute
 196  * @attribute_buffer: A #CoglAttributeBuffer
 197  *
 198  * Sets a new #CoglAttributeBuffer for the attribute.
 199  *
 200  * Stability: unstable
 201  * Since: 1.10
 202  */
 203 void
 204 cogl_attribute_set_buffer (CoglAttribute *attribute,
 205                            CoglAttributeBuffer *attribute_buffer);
 206
 207 /**
 208  * cogl_is_attribute:
 209  * @object: A #CoglObject
 210  *
 211  * Gets whether the given object references a #CoglAttribute.
 212  *
 213  * Return value: %TRUE if the handle references a #CoglAttribute,
 214  *   %FALSE otherwise
 215  */
 216 gboolean
 217 cogl_is_attribute (void *object);
 218
 219 G_END_DECLS
 220
 221 #endif /* __COGL_ATTRIBUTE_H__ */
 222