cogl/cogl-primitive.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_PRIMITIVE_H__
  32 #define __COGL_PRIMITIVE_H__
  33
  34 /* We forward declare the CoglPrimitive type here to avoid some circular
  35  * dependency issues with the following headers.
  36  */
  37 typedef struct _CoglPrimitive CoglPrimitive;
  38
  39 #include <cogl/cogl-vertex-buffer.h> /* for CoglVerticesMode */
  40 #include <cogl/cogl-attribute.h>
  41
  42 G_BEGIN_DECLS
  43
  44 /**
  45  * SECTION:cogl-primitive
  46  * @short_description: Functions for creating, manipulating and drawing
  47  *    primitives
  48  *
  49  * FIXME
  50  */
  51
  52 /**
  53  * CoglVertexP2:
  54  * @x: The x component of a position attribute
  55  * @y: The y component of a position attribute
  56  *
  57  * A convenience vertex definition that can be used with
  58  * cogl_primitive_new_with_v2_attributes().
  59  *
  60  * Since: 1.6
  61  * Stability: Unstable
  62  */
  63 typedef struct
  64 {
  65    float x, y;
  66 } CoglVertexP2;
  67
  68 /**
  69  * CoglVertexP3:
  70  * @x: The x component of a position attribute
  71  * @y: The y component of a position attribute
  72  * @z: The z component of a position attribute
  73  *
  74  * A convenience vertex definition that can be used with
  75  * cogl_primitive_new_with_v3_attributes().
  76  *
  77  * Since: 1.6
  78  * Stability: Unstable
  79  */
  80 typedef struct
  81 {
  82    float x, y, z;
  83 } CoglVertexP3;
  84
  85 /**
  86  * CoglVertexP2C4:
  87  * @x: The x component of a position attribute
  88  * @y: The y component of a position attribute
  89  * @r: The red component of a color attribute
  90  * @b: The green component of a color attribute
  91  * @g: The blue component of a color attribute
  92  * @a: The alpha component of a color attribute
  93  *
  94  * A convenience vertex definition that can be used with
  95  * cogl_primitive_new_with_v2c4_attributes().
  96  *
  97  * Since: 1.6
  98  * Stability: Unstable
  99  */
 100 typedef struct
 101 {
 102    float x, y;
 103    guint8 r, g, b, a;
 104 } CoglVertexP2C4;
 105
 106 /**
 107  * CoglVertexP3C4:
 108  * @x: The x component of a position attribute
 109  * @y: The y component of a position attribute
 110  * @z: The z component of a position attribute
 111  * @r: The red component of a color attribute
 112  * @b: The green component of a color attribute
 113  * @g: The blue component of a color attribute
 114  * @a: The alpha component of a color attribute
 115  *
 116  * A convenience vertex definition that can be used with
 117  * cogl_primitive_new_with_v3c4_attributes().
 118  *
 119  * Since: 1.6
 120  * Stability: Unstable
 121  */
 122 typedef struct
 123 {
 124    float x, y, z;
 125    guint8 r, g, b, a;
 126 } CoglVertexP3C4;
 127
 128 /**
 129  * CoglVertexP2T2:
 130  * @x: The x component of a position attribute
 131  * @y: The y component of a position attribute
 132  * @s: The s component of a texture coordinate attribute
 133  * @t: The t component of a texture coordinate attribute
 134  *
 135  * A convenience vertex definition that can be used with
 136  * cogl_primitive_new_with_v2t2_attributes().
 137  *
 138  * Since: 1.6
 139  * Stability: Unstable
 140  */
 141 typedef struct
 142 {
 143    float x, y;
 144    float s, t;
 145 } CoglVertexP2T2;
 146
 147 /**
 148  * CoglVertexP3T2:
 149  * @x: The x component of a position attribute
 150  * @y: The y component of a position attribute
 151  * @z: The z component of a position attribute
 152  * @s: The s component of a texture coordinate attribute
 153  * @t: The t component of a texture coordinate attribute
 154  *
 155  * A convenience vertex definition that can be used with
 156  * cogl_primitive_new_with_v3t2_attributes().
 157  *
 158  * Since: 1.6
 159  * Stability: Unstable
 160  */
 161 typedef struct
 162 {
 163    float x, y, z;
 164    float s, t;
 165 } CoglVertexP3T2;
 166
 167
 168 /**
 169  * CoglVertexP2T2C4:
 170  * @x: The x component of a position attribute
 171  * @y: The y component of a position attribute
 172  * @s: The s component of a texture coordinate attribute
 173  * @t: The t component of a texture coordinate attribute
 174  * @r: The red component of a color attribute
 175  * @b: The green component of a color attribute
 176  * @g: The blue component of a color attribute
 177  * @a: The alpha component of a color attribute
 178  *
 179  * A convenience vertex definition that can be used with
 180  * cogl_primitive_new_with_v3t2c4_attributes().
 181  *
 182  * Since: 1.6
 183  * Stability: Unstable
 184  */
 185 typedef struct
 186 {
 187    float x, y;
 188    float s, t;
 189    guint8 r, g, b, a;
 190 } CoglVertexP2T2C4;
 191
 192 /**
 193  * CoglVertexP3T2C4:
 194  * @x: The x component of a position attribute
 195  * @y: The y component of a position attribute
 196  * @z: The z component of a position attribute
 197  * @s: The s component of a texture coordinate attribute
 198  * @t: The t component of a texture coordinate attribute
 199  * @r: The red component of a color attribute
 200  * @b: The green component of a color attribute
 201  * @g: The blue component of a color attribute
 202  * @a: The alpha component of a color attribute
 203  *
 204  * A convenience vertex definition that can be used with
 205  * cogl_primitive_new_with_v3t2c4_attributes().
 206  *
 207  * Since: 1.6
 208  * Stability: Unstable
 209  */
 210 typedef struct
 211 {
 212    float x, y, z;
 213    float s, t;
 214    guint8 r, g, b, a;
 215 } CoglVertexP3T2C4;
 216
 217 /**
 218  * cogl_primitive_new:
 219  * @mode: A #CoglVerticesMode defining how to draw the vertices
 220  * @n_vertices: The number of vertices to process when drawing
 221  * @Varargs: A %NULL terminated list of attributes
 222  *
 223  * Combines a set of #CoglAttribute<!-- -->s with a specific draw @mode
 224  * and defines a vertex count so a #CoglPrimitive object can be retained and
 225  * drawn later with no addition information required.
 226  *
 227  * The value passed as @n_vertices will simply update the
 228  * #CoglPrimitive::n_vertices property as if
 229  * cogl_primitive_set_n_vertices() were called. This property defines
 230  * the number of vertices to read when drawing.
 231  *
 232  * Returns: A newly allocated #CoglPrimitive object
 233  *
 234  * Since: 1.6
 235  * Stability: Unstable
 236  */
 237 CoglPrimitive *
 238 cogl_primitive_new (CoglVerticesMode mode,
 239                     int n_vertices,
 240                     ...);
 241
 242 CoglPrimitive *
 243 cogl_primitive_new_with_attributes (CoglVerticesMode mode,
 244                                     int n_vertices,
 245                                     CoglAttribute **attributes,
 246                                     int n_attributes);
 247
 248 /**
 249  * cogl_primitive_new_p2:
 250  * @context: A #CoglContext
 251  * @mode: A #CoglVerticesMode defining how to draw the vertices
 252  * @n_vertices: The number of vertices to read from @data and also
 253  *              the number of vertices to read when later drawing.
 254  * @data: An array of #CoglVertexP2 vertices
 255  *
 256  * Provides a convenient way to describe a primitive, such as a single
 257  * triangle strip or a triangle fan, that will internally allocate the
 258  * necessary #CoglAttributeBuffer storage, describe the position
 259  * attribute with a #CoglAttribute and upload your data.
 260  *
 261  * For example to draw a convex polygon you can do:
 262  * |[
 263  * CoglVertexP2 triangle[] =
 264  * {
 265  *   { 0,   300 },
 266  *   { 150, 0,  },
 267  *   { 300, 300 }
 268  * };
 269  * prim = cogl_primitive_new_p2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 270  *                               3, triangle);
 271  * cogl_primitive_draw (prim);
 272  * ]|
 273  *
 274  * The value passed as @n_vertices is initially used to determine how
 275  * much can be read from @data but it will also be used to update the
 276  * #CoglPrimitive::n_vertices property as if
 277  * cogl_primitive_set_n_vertices() were called. This property defines
 278  * the number of vertices to read when drawing.
 279
 280  * <note>The primitive API doesn't support drawing with sliced
 281  * textures (since switching between slices implies changing state and
 282  * so that implies multiple primitives need to be submitted). You
 283  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 284  * might be used while drawing with this API. If your hardware doesn't
 285  * support non-power of two textures (For example you are using GLES
 286  * 1.1) then you will need to make sure your assets are resized to a
 287  * power-of-two size (though they don't have to be square)</note>
 288  *
 289  * Return value: A newly allocated #CoglPrimitive with a reference of
 290  * 1. This can be freed using cogl_object_unref().
 291  *
 292  * Since: 1.6
 293  * Stability: Unstable
 294  */
 295 CoglPrimitive *
 296 cogl_primitive_new_p2 (CoglContext *context,
 297                        CoglVerticesMode mode,
 298                        int n_vertices,
 299                        const CoglVertexP2 *data);
 300
 301 /**
 302  * cogl_primitive_new_p3:
 303  * @context: A #CoglContext
 304  * @mode: A #CoglVerticesMode defining how to draw the vertices
 305  * @n_vertices: The number of vertices to read from @data and also
 306  *              the number of vertices to read when later drawing.
 307  * @data: An array of #CoglVertexP3 vertices
 308  *
 309  * Provides a convenient way to describe a primitive, such as a single
 310  * triangle strip or a triangle fan, that will internally allocate the
 311  * necessary #CoglAttributeBuffer storage, describe the position
 312  * attribute with a #CoglAttribute and upload your data.
 313  *
 314  * For example to draw a convex polygon you can do:
 315  * |[
 316  * CoglVertexP3 triangle[] =
 317  * {
 318  *   { 0,   300, 0 },
 319  *   { 150, 0,   0 },
 320  *   { 300, 300, 0 }
 321  * };
 322  * prim = cogl_primitive_new_p3 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 323  *                               3, triangle);
 324  * cogl_primitive_draw (prim);
 325  * ]|
 326  *
 327  * The value passed as @n_vertices is initially used to determine how
 328  * much can be read from @data but it will also be used to update the
 329  * #CoglPrimitive::n_vertices property as if
 330  * cogl_primitive_set_n_vertices() were called. This property defines
 331  * the number of vertices to read when drawing.
 332
 333  * <note>The primitive API doesn't support drawing with sliced
 334  * textures (since switching between slices implies changing state and
 335  * so that implies multiple primitives need to be submitted). You
 336  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 337  * might be used while drawing with this API. If your hardware doesn't
 338  * support non-power of two textures (For example you are using GLES
 339  * 1.1) then you will need to make sure your assets are resized to a
 340  * power-of-two size (though they don't have to be square)</note>
 341  *
 342  * Return value: A newly allocated #CoglPrimitive with a reference of
 343  * 1. This can be freed using cogl_object_unref().
 344  *
 345  * Since: 1.6
 346  * Stability: Unstable
 347  */
 348 CoglPrimitive *
 349 cogl_primitive_new_p3 (CoglContext *context,
 350                        CoglVerticesMode mode,
 351                        int n_vertices,
 352                        const CoglVertexP3 *data);
 353
 354 /**
 355  * cogl_primitive_new_p2c4:
 356  * @context: A #CoglContext
 357  * @mode: A #CoglVerticesMode defining how to draw the vertices
 358  * @n_vertices: The number of vertices to read from @data and also
 359  *              the number of vertices to read when later drawing.
 360  * @data: An array of #CoglVertexP2C4 vertices
 361  *
 362  * Provides a convenient way to describe a primitive, such as a single
 363  * triangle strip or a triangle fan, that will internally allocate the
 364  * necessary #CoglAttributeBuffer storage, describe the position
 365  * and color attributes with #CoglAttribute<!-- -->s and upload
 366  * your data.
 367  *
 368  * For example to draw a convex polygon with a linear gradient you
 369  * can do:
 370  * |[
 371  * CoglVertexP2C4 triangle[] =
 372  * {
 373  *   { 0,   300,  0xff, 0x00, 0x00, 0xff },
 374  *   { 150, 0,    0x00, 0xff, 0x00, 0xff },
 375  *   { 300, 300,  0xff, 0x00, 0x00, 0xff }
 376  * };
 377  * prim = cogl_primitive_new_p2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 378  *                                 3, triangle);
 379  * cogl_primitive_draw (prim);
 380  * ]|
 381  *
 382  * The value passed as @n_vertices is initially used to determine how
 383  * much can be read from @data but it will also be used to update the
 384  * #CoglPrimitive::n_vertices property as if
 385  * cogl_primitive_set_n_vertices() were called. This property defines
 386  * the number of vertices to read when drawing.
 387
 388  * <note>The primitive API doesn't support drawing with sliced
 389  * textures (since switching between slices implies changing state and
 390  * so that implies multiple primitives need to be submitted). You
 391  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 392  * might be used while drawing with this API. If your hardware doesn't
 393  * support non-power of two textures (For example you are using GLES
 394  * 1.1) then you will need to make sure your assets are resized to a
 395  * power-of-two size (though they don't have to be square)</note>
 396  *
 397  * Return value: A newly allocated #CoglPrimitive with a reference of
 398  * 1. This can be freed using cogl_object_unref().
 399  *
 400  * Since: 1.6
 401  * Stability: Unstable
 402  */
 403 CoglPrimitive *
 404 cogl_primitive_new_p2c4 (CoglContext *context,
 405                          CoglVerticesMode mode,
 406                          int n_vertices,
 407                          const CoglVertexP2C4 *data);
 408
 409 /**
 410  * cogl_primitive_new_p3c4:
 411  * @context: A #CoglContext
 412  * @mode: A #CoglVerticesMode defining how to draw the vertices
 413  * @n_vertices: The number of vertices to read from @data and also
 414  *              the number of vertices to read when later drawing.
 415  * @data: An array of #CoglVertexP3C4 vertices
 416  *
 417  * Provides a convenient way to describe a primitive, such as a single
 418  * triangle strip or a triangle fan, that will internally allocate the
 419  * necessary #CoglAttributeBuffer storage, describe the position
 420  * and color attributes with #CoglAttribute<!-- -->s and upload
 421  * your data.
 422  *
 423  * For example to draw a convex polygon with a linear gradient you
 424  * can do:
 425  * |[
 426  * CoglVertexP3C4 triangle[] =
 427  * {
 428  *   { 0,   300, 0,  0xff, 0x00, 0x00, 0xff },
 429  *   { 150, 0,   0,  0x00, 0xff, 0x00, 0xff },
 430  *   { 300, 300, 0,  0xff, 0x00, 0x00, 0xff }
 431  * };
 432  * prim = cogl_primitive_new_p3c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 433  *                                 3, triangle);
 434  * cogl_primitive_draw (prim);
 435  * ]|
 436  *
 437  * The value passed as @n_vertices is initially used to determine how
 438  * much can be read from @data but it will also be used to update the
 439  * #CoglPrimitive::n_vertices property as if
 440  * cogl_primitive_set_n_vertices() were called. This property defines
 441  * the number of vertices to read when drawing.
 442
 443  * <note>The primitive API doesn't support drawing with sliced
 444  * textures (since switching between slices implies changing state and
 445  * so that implies multiple primitives need to be submitted). You
 446  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 447  * might be used while drawing with this API. If your hardware doesn't
 448  * support non-power of two textures (For example you are using GLES
 449  * 1.1) then you will need to make sure your assets are resized to a
 450  * power-of-two size (though they don't have to be square)</note>
 451  *
 452  * Return value: A newly allocated #CoglPrimitive with a reference of
 453  * 1. This can be freed using cogl_object_unref().
 454  *
 455  * Since: 1.6
 456  * Stability: Unstable
 457  */
 458 CoglPrimitive *
 459 cogl_primitive_new_p3c4 (CoglContext *context,
 460                          CoglVerticesMode mode,
 461                          int n_vertices,
 462                          const CoglVertexP3C4 *data);
 463
 464 /**
 465  * cogl_primitive_new_p2t2:
 466  * @context: A #CoglContext
 467  * @mode: A #CoglVerticesMode defining how to draw the vertices
 468  * @n_vertices: The number of vertices to read from @data and also
 469  *              the number of vertices to read when later drawing.
 470  * @data: An array of #CoglVertexP2T2 vertices
 471  *
 472  * Provides a convenient way to describe a primitive, such as a single
 473  * triangle strip or a triangle fan, that will internally allocate the
 474  * necessary #CoglAttributeBuffer storage, describe the position and
 475  * texture coordinate attributes with #CoglAttribute<!-- -->s and
 476  * upload your data.
 477  *
 478  * For example to draw a convex polygon with texture mapping you can
 479  * do:
 480  * |[
 481  * CoglVertexP2T2 triangle[] =
 482  * {
 483  *   { 0,   300,  0.0, 1.0},
 484  *   { 150, 0,    0.5, 0.0},
 485  *   { 300, 300,  1.0, 1.0}
 486  * };
 487  * prim = cogl_primitive_new_p2t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 488  *                                 3, triangle);
 489  * cogl_primitive_draw (prim);
 490  * ]|
 491  *
 492  * The value passed as @n_vertices is initially used to determine how
 493  * much can be read from @data but it will also be used to update the
 494  * #CoglPrimitive::n_vertices property as if
 495  * cogl_primitive_set_n_vertices() were called. This property defines
 496  * the number of vertices to read when drawing.
 497
 498  * <note>The primitive API doesn't support drawing with sliced
 499  * textures (since switching between slices implies changing state and
 500  * so that implies multiple primitives need to be submitted). You
 501  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 502  * might be used while drawing with this API. If your hardware doesn't
 503  * support non-power of two textures (For example you are using GLES
 504  * 1.1) then you will need to make sure your assets are resized to a
 505  * power-of-two size (though they don't have to be square)</note>
 506  *
 507  * Return value: A newly allocated #CoglPrimitive with a reference of
 508  * 1. This can be freed using cogl_object_unref().
 509  *
 510  * Since: 1.6
 511  * Stability: Unstable
 512  */
 513 CoglPrimitive *
 514 cogl_primitive_new_p2t2 (CoglContext *context,
 515                          CoglVerticesMode mode,
 516                          int n_vertices,
 517                          const CoglVertexP2T2 *data);
 518
 519 /**
 520  * cogl_primitive_new_p3t2:
 521  * @context: A #CoglContext
 522  * @mode: A #CoglVerticesMode defining how to draw the vertices
 523  * @n_vertices: The number of vertices to read from @data and also
 524  *              the number of vertices to read when later drawing.
 525  * @data: An array of #CoglVertexP3T2 vertices
 526  *
 527  * Provides a convenient way to describe a primitive, such as a single
 528  * triangle strip or a triangle fan, that will internally allocate the
 529  * necessary #CoglAttributeBuffer storage, describe the position and
 530  * texture coordinate attributes with #CoglAttribute<!-- -->s and
 531  * upload your data.
 532  *
 533  * For example to draw a convex polygon with texture mapping you can
 534  * do:
 535  * |[
 536  * CoglVertexP3T2 triangle[] =
 537  * {
 538  *   { 0,   300, 0,  0.0, 1.0},
 539  *   { 150, 0,   0,  0.5, 0.0},
 540  *   { 300, 300, 0,  1.0, 1.0}
 541  * };
 542  * prim = cogl_primitive_new_p3t2 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 543  *                                 3, triangle);
 544  * cogl_primitive_draw (prim);
 545  * ]|
 546  *
 547  * The value passed as @n_vertices is initially used to determine how
 548  * much can be read from @data but it will also be used to update the
 549  * #CoglPrimitive::n_vertices property as if
 550  * cogl_primitive_set_n_vertices() were called. This property defines
 551  * the number of vertices to read when drawing.
 552
 553  * <note>The primitive API doesn't support drawing with sliced
 554  * textures (since switching between slices implies changing state and
 555  * so that implies multiple primitives need to be submitted). You
 556  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 557  * might be used while drawing with this API. If your hardware doesn't
 558  * support non-power of two textures (For example you are using GLES
 559  * 1.1) then you will need to make sure your assets are resized to a
 560  * power-of-two size (though they don't have to be square)</note>
 561  *
 562  * Return value: A newly allocated #CoglPrimitive with a reference of
 563  * 1. This can be freed using cogl_object_unref().
 564  *
 565  * Since: 1.6
 566  * Stability: Unstable
 567  */
 568 CoglPrimitive *
 569 cogl_primitive_new_p3t2 (CoglContext *context,
 570                          CoglVerticesMode mode,
 571                          int n_vertices,
 572                          const CoglVertexP3T2 *data);
 573
 574 /**
 575  * cogl_primitive_new_p2t2c4:
 576  * @context: A #CoglContext
 577  * @mode: A #CoglVerticesMode defining how to draw the vertices
 578  * @n_vertices: The number of vertices to read from @data and also
 579  *              the number of vertices to read when later drawing.
 580  * @data: An array of #CoglVertexP2T2C4 vertices
 581  *
 582  * Provides a convenient way to describe a primitive, such as a single
 583  * triangle strip or a triangle fan, that will internally allocate the
 584  * necessary #CoglAttributeBuffer storage, describe the position, texture
 585  * coordinate and color attributes with #CoglAttribute<!-- -->s and
 586  * upload your data.
 587  *
 588  * For example to draw a convex polygon with texture mapping and a
 589  * linear gradient you can do:
 590  * |[
 591  * CoglVertexP2T2C4 triangle[] =
 592  * {
 593  *   { 0,   300,  0.0, 1.0,  0xff, 0x00, 0x00, 0xff},
 594  *   { 150, 0,    0.5, 0.0,  0x00, 0xff, 0x00, 0xff},
 595  *   { 300, 300,  1.0, 1.0,  0xff, 0x00, 0x00, 0xff}
 596  * };
 597  * prim = cogl_primitive_new_p2t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 598  *                                   3, triangle);
 599  * cogl_primitive_draw (prim);
 600  * ]|
 601  *
 602  * The value passed as @n_vertices is initially used to determine how
 603  * much can be read from @data but it will also be used to update the
 604  * #CoglPrimitive::n_vertices property as if
 605  * cogl_primitive_set_n_vertices() were called. This property defines
 606  * the number of vertices to read when drawing.
 607
 608  * <note>The primitive API doesn't support drawing with sliced
 609  * textures (since switching between slices implies changing state and
 610  * so that implies multiple primitives need to be submitted). You
 611  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 612  * might be used while drawing with this API. If your hardware doesn't
 613  * support non-power of two textures (For example you are using GLES
 614  * 1.1) then you will need to make sure your assets are resized to a
 615  * power-of-two size (though they don't have to be square)</note>
 616  *
 617  * Return value: A newly allocated #CoglPrimitive with a reference of
 618  * 1. This can be freed using cogl_object_unref().
 619  *
 620  * Since: 1.6
 621  * Stability: Unstable
 622  */
 623 CoglPrimitive *
 624 cogl_primitive_new_p2t2c4 (CoglContext *context,
 625                            CoglVerticesMode mode,
 626                            int n_vertices,
 627                            const CoglVertexP2T2C4 *data);
 628
 629 /**
 630  * cogl_primitive_new_p3t2c4:
 631  * @context: A #CoglContext
 632  * @mode: A #CoglVerticesMode defining how to draw the vertices
 633  * @n_vertices: The number of vertices to read from @data and also
 634  *              the number of vertices to read when later drawing.
 635  * @data: An array of #CoglVertexP3T2C4 vertices
 636  *
 637  * Provides a convenient way to describe a primitive, such as a single
 638  * triangle strip or a triangle fan, that will internally allocate the
 639  * necessary #CoglAttributeBuffer storage, describe the position, texture
 640  * coordinate and color attributes with #CoglAttribute<!-- -->s and
 641  * upload your data.
 642  *
 643  * For example to draw a convex polygon with texture mapping and a
 644  * linear gradient you can do:
 645  * |[
 646  * CoglVertexP3T2C4 triangle[] =
 647  * {
 648  *   { 0,   300, 0,  0.0, 1.0,  0xff, 0x00, 0x00, 0xff},
 649  *   { 150, 0,   0,  0.5, 0.0,  0x00, 0xff, 0x00, 0xff},
 650  *   { 300, 300, 0,  1.0, 1.0,  0xff, 0x00, 0x00, 0xff}
 651  * };
 652  * prim = cogl_primitive_new_p3t2c4 (COGL_VERTICES_MODE_TRIANGLE_FAN,
 653  *                                   3, triangle);
 654  * cogl_primitive_draw (prim);
 655  * ]|
 656  *
 657  * The value passed as @n_vertices is initially used to determine how
 658  * much can be read from @data but it will also be used to update the
 659  * #CoglPrimitive::n_vertices property as if
 660  * cogl_primitive_set_n_vertices() were called. This property defines
 661  * the number of vertices to read when drawing.
 662
 663  * <note>The primitive API doesn't support drawing with sliced
 664  * textures (since switching between slices implies changing state and
 665  * so that implies multiple primitives need to be submitted). You
 666  * should pass the %COGL_TEXTURE_NO_SLICING flag to all textures that
 667  * might be used while drawing with this API. If your hardware doesn't
 668  * support non-power of two textures (For example you are using GLES
 669  * 1.1) then you will need to make sure your assets are resized to a
 670  * power-of-two size (though they don't have to be square)</note>
 671  *
 672  * Return value: A newly allocated #CoglPrimitive with a reference of
 673  * 1. This can be freed using cogl_object_unref().
 674  *
 675  * Since: 1.6
 676  * Stability: Unstable
 677  */
 678 CoglPrimitive *
 679 cogl_primitive_new_p3t2c4 (CoglContext *context,
 680                            CoglVerticesMode mode,
 681                            int n_vertices,
 682                            const CoglVertexP3T2C4 *data);
 683 int
 684 cogl_primitive_get_first_vertex (CoglPrimitive *primitive);
 685
 686 void
 687 cogl_primitive_set_first_vertex (CoglPrimitive *primitive,
 688                                  int first_vertex);
 689
 690 #define cogl_primitive_get_n_vertices cogl_primitive_get_n_vertices_EXP
 691 /**
 692  * cogl_primitive_get_n_vertices:
 693  * @primitive: A #CoglPrimitive object
 694  *
 695  * Queries the number of vertices to read when drawing the given
 696  * @primitive. Usually this value is implicitly set when associating
 697  * vertex data or indices with a #CoglPrimitive.
 698  *
 699  * If cogl_primitive_set_indices() has been used to associate a
 700  * sequence of #CoglIndices with the given @primitive then the
 701  * number of vertices to read can also be phrased as the number
 702  * of indices to read.
 703  *
 704  * <note>To be clear; it doesn't refer to the number of vertices - in
 705  * terms of data - associated with the primitive it's just the number
 706  * of vertices to read and draw.</note>
 707  *
 708  * Returns: The number of vertices to read when drawing.
 709  *
 710  * Since: 1.8
 711  * Stability: unstable
 712  */
 713 int
 714 cogl_primitive_get_n_vertices (CoglPrimitive *primitive);
 715
 716 #define cogl_primitive_set_n_vertices cogl_primitive_set_n_vertices_EXP
 717 /**
 718  * cogl_primitive_set_n_vertices:
 719  * @primitive: A #CoglPrimitive object
 720  * @n_vertices: The number of vertices to read when drawing.
 721  *
 722  * Specifies how many vertices should be read when drawing the given
 723  * @primitive.
 724  *
 725  * Usually this value is set implicitly when associating vertex data
 726  * or indices with a #CoglPrimitive.
 727  *
 728  * <note>To be clear; it doesn't refer to the number of vertices - in
 729  * terms of data - associated with the primitive it's just the number
 730  * of vertices to read and draw.</note>
 731  *
 732  * Since: 1.8
 733  * Stability: unstable
 734  */
 735 void
 736 cogl_primitive_set_n_vertices (CoglPrimitive *primitive,
 737                                int n_vertices);
 738
 739 CoglVerticesMode
 740 cogl_primitive_get_mode (CoglPrimitive *primitive);
 741
 742 void
 743 cogl_primitive_set_mode (CoglPrimitive *primitive,
 744                          CoglVerticesMode mode);
 745
 746 /**
 747  * cogl_primitive_set_attributes:
 748  * @primitive: A #CoglPrimitive object
 749  * @attributes: A %NULL terminated array of #CoglAttribute
 750  *              pointers
 751  *
 752  * Replaces all the attributes of the given #CoglPrimitive object.
 753  *
 754  * Since: 1.6
 755  * Stability: Unstable
 756  */
 757 void
 758 cogl_primitive_set_attributes (CoglPrimitive *primitive,
 759                                CoglAttribute **attributes,
 760                                int n_attributes);
 761
 762 #define cogl_primitive_set_indices cogl_primitive_set_indices_EXP
 763 /**
 764  * cogl_primitive_set_indices:
 765  * @primitive: A #CoglPrimitive
 766  * @indices: A #CoglIndices array
 767  * @n_indices: The number of indices to reference when drawing
 768  *
 769  * Associates a sequence of #CoglIndices with the given @primitive.
 770  *
 771  * #CoglIndices provide a way to virtualize your real vertex data by
 772  * providing a sequence of indices that index into your real vertex
 773  * data. The GPU will walk though the index values to indirectly
 774  * lookup the data for each vertex instead of sequentially walking
 775  * through the data directly. This lets you save memory by indexing
 776  * shared data multiple times instead of duplicating the data.
 777  *
 778  * The value passed as @n_indices will simply update the
 779  * #CoglPrimitive::n_vertices property as if
 780  * cogl_primitive_set_n_vertices() were called. This property defines
 781  * the number of vertices to draw or, put another way, how many
 782  * indices should be read from @indices when drawing.
 783  *
 784  * <note>The #CoglPrimitive::first_vertex property also affects
 785  * drawing with indices by defining the first entry of the indices to
 786  * start drawing from.</note>
 787  *
 788  * Since: 1.10
 789  * Stability: unstable
 790  */
 791 void
 792 cogl_primitive_set_indices (CoglPrimitive *primitive,
 793                             CoglIndices *indices,
 794                             int n_indices);
 795
 796 /**
 797  * cogl_primitive_get_indices:
 798  * @primitive: A #CoglPrimitive
 799  *
 800  * Return value: the indices that were set with
 801  * cogl_primitive_set_indices() or %NULL if no indices were set.
 802  *
 803  * Since: 1.10
 804  * Stability: unstable
 805  */
 806 CoglIndices *
 807 cogl_primitive_get_indices (CoglPrimitive *primitive);
 808
 809 /**
 810  * cogl_primitive_copy:
 811  * @primitive: A primitive copy
 812  *
 813  * Makes a copy of an existing #CoglPrimitive. Note that the primitive
 814  * is a shallow copy which means it will use the same attributes and
 815  * attribute buffers as the original primitive.
 816  *
 817  * Return value: the new primitive
 818  * Since: 1.10
 819  * Stability: unstable
 820  */
 821 CoglPrimitive *
 822 cogl_primitive_copy (CoglPrimitive *primitive);
 823
 824 /**
 825  * cogl_is_primitive:
 826  * @object: A #CoglObject
 827  *
 828  * Gets whether the given object references a #CoglPrimitive.
 829  *
 830  * Returns: %TRUE if the handle references a #CoglPrimitive,
 831  *   %FALSE otherwise
 832  *
 833  * Since: 1.6
 834  * Stability: Unstable
 835  */
 836 gboolean
 837 cogl_is_primitive (void *object);
 838
 839 /**
 840  * CoglPrimitiveAttributeCallback:
 841  * @primitive: The #CoglPrimitive whose attributes are being iterated
 842  * @attribute: The #CoglAttribute
 843  * @user_data: The private data passed to cogl_primitive_foreach_attribute()
 844  *
 845  * The callback prototype used with cogl_primitive_foreach_attribute()
 846  * for iterating all the attributes of a #CoglPrimitive.
 847  *
 848  * The function should return TRUE to continue iteration or FALSE to
 849  * stop.
 850  *
 851  * Since: 1.10
 852  * Stability: Unstable
 853  */
 854 typedef gboolean (* CoglPrimitiveAttributeCallback) (CoglPrimitive *primitive,
 855                                                      CoglAttribute *attribute,
 856                                                      void *user_data);
 857
 858 /**
 859  * cogl_primitive_foreach_attribute:
 860  * @primitive: A #CoglPrimitive object
 861  * @callback: A #CoglPrimitiveAttributeCallback to be called for each attribute
 862  * @user_data: Private data that will be passed to the callback
 863  *
 864  * Iterates all the attributes of the given #CoglPrimitive.
 865  *
 866  * Since: 1.10
 867  * Stability: Unstable
 868  */
 869 void
 870 cogl_primitive_foreach_attribute (CoglPrimitive *primitive,
 871                                   CoglPrimitiveAttributeCallback callback,
 872                                   void *user_data);
 873
 874 G_END_DECLS
 875
 876 #endif /* __COGL_PRIMITIVE_H__ */
 877