Vertex Attributes

## Vertex Attributes Vertex Attributes — Functions for declaring and drawing vertex attributes |

## Synopsis

    CoglAttribute *     cogl_attribute_new                  (CoglAttributeBuffer *attribute_buffer,
                                                             const char *name,
                                                             gsize stride,
                                                             gsize offset,
                                                             int components,
                                                             CoglAttributeType type);
    gboolean            cogl_is_attribute                   (void *object);
    void                cogl_attribute_set_normalized       (CoglAttribute *attribute,
                                                             gboolean normalized);
    gboolean            cogl_attribute_get_normalized       (CoglAttribute *attribute);
    CoglAttributeBuffer * cogl_attribute_get_buffer         (CoglAttribute *attribute);
    void                cogl_attribute_set_buffer           (CoglAttribute *attribute,
                                                             CoglAttributeBuffer *attribute_buffer);

## Description

FIXME

## Details

### cogl_attribute_new ()

    CoglAttribute *     cogl_attribute_new                  (CoglAttributeBuffer *attribute_buffer,
                                                             const char *name,
                                                             gsize stride,
                                                             gsize offset,
                                                             int components,
                                                             CoglAttributeType type);

Describes the layout for a list of vertex attribute values (For example, a list of texture coordinates or colors).

The `name` is used to access the attribute inside a GLSL vertex shader and there are some special names you should use if they are applicable:

- "cogl_position_in" (used for vertex positions)
- "cogl_color_in" (used for vertex colors)
- "cogl_tex_coord0_in", "cogl_tex_coord1", ... (used for vertex texture coordinates)
- "cogl_normal_in" (used for vertex normals)

The attribute values corresponding to different vertices can either be tightly packed or interleaved with other attribute values. For example it's common to define a structure for a single vertex like:

    1
    2
    3
    4
    5
    typedef struct
    {
      float x, y, z; /* position attribute */
      float s, t; /* texture coordinate attribute */
    } MyVertex;

And then create an array of vertex data something like:

    1
    MyVertex vertices[100] = { .... }

In this case, to describe either the position or texture coordinate attribute you have to move <pre>sizeof (MyVertex)</pre> bytes to move from one vertex to the next. This is called the attribute `stride`. If you weren't interleving attributes and you instead had a packed array of float x, y pairs then the attribute stride would be <pre>(2 * sizeof (float))</pre>. So the `stride` is the number of bytes to move to find the attribute value of the next vertex.

Normally a list of attributes starts at the beginning of an array. So for the <pre>MyVertex</pre> example above the `offset` is the offset inside the <pre>MyVertex</pre> structure to the first component of the attribute. For the texture coordinate attribute the offset would be <pre>offsetof (MyVertex, s)</pre> or instead of using the offsetof macro you could use <pre>sizeof (float) * 3</pre>. If you've divided your `array` into blocks of non-interleved attributes then you will need to calculate the `offset` as the number of bytes in blocks preceding the attribute you're describing.

An attribute often has more than one component. For example a color is often comprised of 4 red, green, blue and alpha `components`, and a position may be comprised of 2 x and y `components`. You should aim to keep the number of components to a minimum as more components means more data needs to be mapped into the GPU which can be a bottlneck when dealing with a large number of vertices.

Finally you need to specify the component data type. Here you should aim to use the smallest type that meets your precision requirements. Again the larger the type then more data needs to be mapped into the GPU which can be a bottlneck when dealing with a large number of vertices.

`attribute_buffer` : | The CoglAttributeBuffer containing the actual attribute data
`name` : | The name of the attribute (used to reference it from GLSL)
`stride` : | The number of bytes to jump to get to the next attribute value for the next vertex. (Usually <pre>sizeof (MyVertex)</pre>)
`offset` : | The byte offset from the start of `attribute_buffer` for the first attribute value. (Usually <pre>offsetof (MyVertex, component0)</pre>
`components` : | The number of components (e.g. 4 for an rgba color or 3 for and (x,y,z) position)
`type` : | FIXME
Returns : | A newly allocated CoglAttribute describing the layout for a list of attribute values stored in `array`.

Since 1.4

Stability Level: Unstable

### cogl_is_attribute ()

    gboolean            cogl_is_attribute                   (void *object);

Gets whether the given object references a CoglAttribute.

`object` : | A CoglObject
Returns : | `TRUE` if the handle references a CoglAttribute, `FALSE` otherwise

### cogl_attribute_set_normalized ()

    void                cogl_attribute_set_normalized       (CoglAttribute *attribute,
                                                             gboolean normalized);

Sets whether fixed point attribute types are mapped to the range 0→1. For example when this property is TRUE and a `COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE` type is used then the value 255 will be mapped to 1.0.

The default value of this property depends on the name of the attribute. For the builtin properties cogl_color_in and cogl_normal_in it will default to TRUE and for all other names it will default to FALSE.

`attribute` : | A CoglAttribute
`normalized` : | The new value for the normalized property.

Since 1.10

Stability Level: Unstable

### cogl_attribute_get_normalized ()

    gboolean            cogl_attribute_get_normalized       (CoglAttribute *attribute);

`attribute` : | A CoglAttribute
Returns : | the value of the normalized property set with `cogl_attribute_set_normalized()`.

Since 1.10

Stability Level: Unstable

### cogl_attribute_get_buffer ()

    CoglAttributeBuffer * cogl_attribute_get_buffer         (CoglAttribute *attribute);

`attribute` : | A CoglAttribute
Returns : | the CoglAttributeBuffer that was set with `cogl_attribute_set_buffer()` or `cogl_attribute_new()`.

Since 1.10

Stability Level: Unstable

### cogl_attribute_set_buffer ()

    void                cogl_attribute_set_buffer           (CoglAttribute *attribute,
                                                             CoglAttributeBuffer *attribute_buffer);

Sets a new CoglAttributeBuffer for the attribute.

`attribute` : | A CoglAttribute
`attribute_buffer` : | A CoglAttributeBuffer

Since 1.10

Stability Level: Unstable