## Primitives Primitives — Functions for creating, manipulating and drawing primitives |

## Synopsis

                        CoglPrimitive;
    CoglPrimitive *     cogl_primitive_new                  (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             ...);
    CoglPrimitive *     cogl_primitive_new_with_attributes  (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             CoglAttribute **attributes,
                                                             int n_attributes);
    CoglPrimitive *     cogl_primitive_new_p2               (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2 *data);
    CoglPrimitive *     cogl_primitive_new_p3               (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3 *data);
    CoglPrimitive *     cogl_primitive_new_p2c4             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2C4 *data);
    CoglPrimitive *     cogl_primitive_new_p3c4             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3C4 *data);
    CoglPrimitive *     cogl_primitive_new_p2t2             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2T2 *data);
    CoglPrimitive *     cogl_primitive_new_p3t2             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3T2 *data);
    CoglPrimitive *     cogl_primitive_new_p2t2c4           (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2T2C4 *data);
    CoglPrimitive *     cogl_primitive_new_p3t2c4           (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3T2C4 *data);
    gboolean            cogl_is_primitive                   (void *object);
    int                 cogl_primitive_get_first_vertex     (CoglPrimitive *primitive);
    void                cogl_primitive_set_first_vertex     (CoglPrimitive *primitive,
                                                             int first_vertex);
    #define             cogl_primitive_get_n_vertices
    #define             cogl_primitive_set_n_vertices
    CoglVerticesMode    cogl_primitive_get_mode             (CoglPrimitive *primitive);
    void                cogl_primitive_set_mode             (CoglPrimitive *primitive,
                                                             CoglVerticesMode mode);
    void                cogl_primitive_set_attributes       (CoglPrimitive *primitive,
                                                             CoglAttribute **attributes,
                                                             int n_attributes);
    #define             cogl_primitive_set_indices
    void                cogl_primitive_draw                 (CoglPrimitive *primitive);

## Description

FIXME

## Details

### CoglPrimitive

    typedef struct _CoglPrimitive CoglPrimitive;

### cogl_primitive_new ()

    CoglPrimitive *     cogl_primitive_new                  (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             ...);

Combines a set of CoglAttributes with a specific draw `mode` and defines a vertex count so a CoglPrimitive object can be retained and drawn later with no addition information required.

The value passed as `n_vertices` will simply update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to process when drawing
`Varargs` : | A `NULL` terminated list of attributes
Returns : | A newly allocated CoglPrimitive object

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_with_attributes ()

    CoglPrimitive *     cogl_primitive_new_with_attributes  (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             CoglAttribute **attributes,
                                                             int n_attributes);

### cogl_primitive_new_p2 ()

    CoglPrimitive *     cogl_primitive_new_p2               (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position attribute with a CoglAttribute and upload your data.

For example to draw a convex polygon you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP2 triangle[] =
    {
      { 0,   300 },
      { 150, 0,  },
      { 300, 300 }
    };
    prim = cogl_primitive_new_p2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                  3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP2 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p3 ()

    CoglPrimitive *     cogl_primitive_new_p3               (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position attribute with a CoglAttribute and upload your data.

For example to draw a convex polygon you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP3 triangle[] =
    {
      { 0,   300, 0 },
      { 150, 0,   0 },
      { 300, 300, 0 }
    };
    prim = cogl_primitive_new_p3 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                  3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP3 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p2c4 ()

    CoglPrimitive *     cogl_primitive_new_p2c4             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2C4 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position and color attributes with CoglAttributes and upload your data.

For example to draw a convex polygon with a linear gradient you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP2C4 triangle[] =
    {
      { 0,   300,  0xff, 0x00, 0x00, 0xff },
      { 150, 0,    0x00, 0xff, 0x00, 0xff },
      { 300, 300,  0xff, 0x00, 0x00, 0xff }
    };
    prim = cogl_primitive_new_p2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                    3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP2C4 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p3c4 ()

    CoglPrimitive *     cogl_primitive_new_p3c4             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3C4 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position and color attributes with CoglAttributes and upload your data.

For example to draw a convex polygon with a linear gradient you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP3C4 triangle[] =
    {
      { 0,   300, 0,  0xff, 0x00, 0x00, 0xff },
      { 150, 0,   0,  0x00, 0xff, 0x00, 0xff },
      { 300, 300, 0,  0xff, 0x00, 0x00, 0xff }
    };
    prim = cogl_primitive_new_p3c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                    3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP3C4 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p2t2 ()

    CoglPrimitive *     cogl_primitive_new_p2t2             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2T2 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position and texture coordinate attributes with CoglAttributes and upload your data.

For example to draw a convex polygon with texture mapping you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP2T2 triangle[] =
    {
      { 0,   300,  0.0, 1.0},
      { 150, 0,    0.5, 0.0},
      { 300, 300,  1.0, 1.0}
    };
    prim = cogl_primitive_new_p2t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                    3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP2T2 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p3t2 ()

    CoglPrimitive *     cogl_primitive_new_p3t2             (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3T2 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position and texture coordinate attributes with CoglAttributes and upload your data.

For example to draw a convex polygon with texture mapping you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP3T2 triangle[] =
    {
      { 0,   300, 0,  0.0, 1.0},
      { 150, 0,   0,  0.5, 0.0},
      { 300, 300, 0,  1.0, 1.0}
    };
    prim = cogl_primitive_new_p3t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                    3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP3T2 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p2t2c4 ()

    CoglPrimitive *     cogl_primitive_new_p2t2c4           (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP2T2C4 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position, texture coordinate and color attributes with CoglAttributes and upload your data.

For example to draw a convex polygon with texture mapping and a linear gradient you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP2T2C4 triangle[] =
    {
      { 0,   300,  0.0, 1.0,  0xff, 0x00, 0x00, 0xff},
      { 150, 0,    0.5, 0.0,  0x00, 0xff, 0x00, 0xff},
      { 300, 300,  1.0, 1.0,  0xff, 0x00, 0x00, 0xff}
    };
    prim = cogl_primitive_new_p2t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                      3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP2T2C4 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_primitive_new_p3t2c4 ()

    CoglPrimitive *     cogl_primitive_new_p3t2c4           (CoglVerticesMode mode,
                                                             int n_vertices,
                                                             const CoglVertexP3T2C4 *data);

Provides a convenient way to describe a primitive, such as a single triangle strip or a triangle fan, that will internally allocate the necessary CoglAttributeBuffer storage, describe the position, texture coordinate and color attributes with CoglAttributes and upload your data.

For example to draw a convex polygon with texture mapping and a linear gradient you can do:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    CoglVertexP3T2C4 triangle[] =
    {
      { 0,   300, 0,  0.0, 1.0,  0xff, 0x00, 0x00, 0xff},
      { 150, 0,   0,  0.5, 0.0,  0x00, 0xff, 0x00, 0xff},
      { 300, 300, 0,  1.0, 1.0,  0xff, 0x00, 0x00, 0xff}
    };
    prim = cogl_primitive_new_p3t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
                                      3, triangle);
    cogl_primitive_draw (prim);

The value passed as `n_vertices` is initially used to determine how much can be read from `data` but it will also be used to update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to read when drawing.

### Note

The primitive API doesn't support drawing with sliced textures (since switching between slices implies changing state and so that implies multiple primitives need to be submitted). You should pass the `COGL_TEXTURE_NO_SLICING` flag to all textures that might be used while drawing with this API. If your hardware doesn't support non-power of two textures (For example you are using GLES 1.1) then you will need to make sure your assets are resized to a power-of-two size (though they don't have to be square)

`mode` : | A CoglVerticesMode defining how to draw the vertices
`n_vertices` : | The number of vertices to read from `data` and also the number of vertices to read when later drawing.
`data` : | An array of CoglVertexP3T2C4 vertices
Returns : | A newly allocated CoglPrimitive with a reference of 1. This can be freed using `cogl_object_unref()`.

Since 1.6

Stability Level: Unstable

### cogl_is_primitive ()

    gboolean            cogl_is_primitive                   (void *object);

Gets whether the given object references a CoglPrimitive.

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

Since 1.6

Stability Level: Unstable

### cogl_primitive_get_first_vertex ()

    int                 cogl_primitive_get_first_vertex     (CoglPrimitive *primitive);

### cogl_primitive_set_first_vertex ()

    void                cogl_primitive_set_first_vertex     (CoglPrimitive *primitive,
                                                             int first_vertex);

### cogl_primitive_get_n_vertices

    #define cogl_primitive_get_n_vertices cogl_primitive_get_n_vertices_EXP

Queries the number of vertices to read when drawing the given `primitive`. Usually this value is implicitly set when associating vertex data or indices with a CoglPrimitive.

If `cogl_primitive_set_indices()` has been used to associate a sequence of CoglIndices with the given `primitive` then the number of vertices to read can also be phrased as the number of indices to read.

### Note

To be clear; it doesn't refer to the number of vertices - in terms of data - associated with the primitive it's just the number of vertices to read and draw.

`primitive` : | A CoglPrimitive object
Returns : | The number of vertices to read when drawing.

Since 1.8

Stability Level: Unstable

### cogl_primitive_set_n_vertices

    #define cogl_primitive_set_n_vertices cogl_primitive_set_n_vertices_EXP

Specifies how many vertices should be read when drawing the given `primitive`.

Usually this value is set implicitly when associating vertex data or indices with a CoglPrimitive.

### Note

To be clear; it doesn't refer to the number of vertices - in terms of data - associated with the primitive it's just the number of vertices to read and draw.

`primitive` : | A CoglPrimitive object
`n_vertices` : | The number of vertices to read when drawing.

Since 1.8

Stability Level: Unstable

### cogl_primitive_get_mode ()

    CoglVerticesMode    cogl_primitive_get_mode             (CoglPrimitive *primitive);

### cogl_primitive_set_mode ()

    void                cogl_primitive_set_mode             (CoglPrimitive *primitive,
                                                             CoglVerticesMode mode);

### cogl_primitive_set_attributes ()

    void                cogl_primitive_set_attributes       (CoglPrimitive *primitive,
                                                             CoglAttribute **attributes,
                                                             int n_attributes);

Replaces all the attributes of the given CoglPrimitive object.

`primitive` : | A CoglPrimitive object
`attributes` : | A `NULL` terminated array of CoglAttribute pointers

Since 1.6

Stability Level: Unstable

### cogl_primitive_set_indices

    #define cogl_primitive_set_indices cogl_primitive_set_indices_EXP

Associates a sequence of CoglIndices with the given `primitive`.

CoglIndices provide a way to virtualize your real vertex data by providing a sequence of indices that index into your real vertex data. The GPU will walk though the index values to indirectly lookup the data for each vertex instead of sequentially walking through the data directly. This lets you save memory by indexing shared data multiple times instead of duplicating the data.

The value passed as `n_indices` will simply update the "n_vertices" property as if `cogl_primitive_set_n_vertices()` were called. This property defines the number of vertices to draw or, put another way, how many indices should be read from `indices` when drawing.

### Note

The "first_vertex" property also affects drawing with indices by defining the first entry of the indices to start drawing from.

`primitive` : | A CoglPrimitive
`indices` : | A CoglIndices array
`n_indices` : | The number of indices to reference when drawing

Since 1.10

Stability Level: Unstable

### cogl_primitive_draw ()

    void                cogl_primitive_draw                 (CoglPrimitive *primitive);

Draw the given `primitive` with the current source material.

`primitive` : | A CoglPrimitive object

Since 1.6

Stability Level: Unstable