cogl/cogl-primitives.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2007,2008,2009 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
  19  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  *
  21  *
  22  */
  23
  24 #ifndef __COGL_PRIMITIVES_H
  25 #define __COGL_PRIMITIVES_H
  26
  27 #include <glib.h>
  28
  29 G_BEGIN_DECLS
  30
  31 /**
  32  * SECTION:cogl-primitives
  33  * @short_description: Functions that draw various primitive 3D shapes
  34  *
  35  * The primitives API provides utilities for drawing some
  36  * common 3D shapes in a more convenient way than the CoglVertexBuffer
  37  * API provides.
  38  */
  39
  40 /**
  41  * cogl_rectangle:
  42  * @x_1: X coordinate of the top-left corner
  43  * @y_1: Y coordinate of the top-left corner
  44  * @x_2: X coordinate of the bottom-right corner
  45  * @y_2: Y coordinate of the bottom-right corner
  46  *
  47  * Fills a rectangle at the given coordinates with the current source material
  48  **/
  49 void
  50 cogl_rectangle (float x_1,
  51                 float y_1,
  52                 float x_2,
  53                 float y_2);
  54
  55 /**
  56  * cogl_rectangle_with_texture_coords:
  57  * @x1: x coordinate upper left on screen.
  58  * @y1: y coordinate upper left on screen.
  59  * @x2: x coordinate lower right on screen.
  60  * @y2: y coordinate lower right on screen.
  61  * @tx1: x part of texture coordinate to use for upper left pixel
  62  * @ty1: y part of texture coordinate to use for upper left pixel
  63  * @tx2: x part of texture coordinate to use for lower right pixel
  64  * @ty2: y part of texture coordinate to use for left pixel
  65  *
  66  * Draw a rectangle using the current material and supply texture coordinates
  67  * to be used for the first texture layer of the material. To draw the entire
  68  * texture pass in @tx1=0.0 @ty1=0.0 @tx2=1.0 @ty2=1.0.
  69  *
  70  * Since: 1.0
  71  */
  72 void
  73 cogl_rectangle_with_texture_coords (float  x1,
  74                                     float  y1,
  75                                     float  x2,
  76                                     float  y2,
  77                                     float  tx1,
  78                                     float  ty1,
  79                                     float  tx2,
  80                                     float  ty2);
  81
  82 /**
  83  * cogl_rectangle_with_multitexture_coords:
  84  * @x1: x coordinate upper left on screen.
  85  * @y1: y coordinate upper left on screen.
  86  * @x2: x coordinate lower right on screen.
  87  * @y2: y coordinate lower right on screen.
  88  * @tex_coords: (in) (array) (transfer none): An array containing groups of
  89  *   4 float values: [tx1, ty1, tx2, ty2] that are interpreted as two texture
  90  *   coordinates; one for the upper left texel, and one for the lower right
  91  *   texel. Each value should be between 0.0 and 1.0, where the coordinate
  92  *   (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the
  93  *   bottom right.
  94  * @tex_coords_len: The length of the tex_coords array. (e.g. for one layer
  95  *   and one group of texture coordinates, this would be 4)
  96  *
  97  * This function draws a rectangle using the current source material to
  98  * texture or fill with. As a material may contain multiple texture layers
  99  * this interface lets you supply texture coordinates for each layer of the
 100  * material.
 101  *
 102  * The first pair of coordinates are for the first layer (with the smallest
 103  * layer index) and if you supply less texture coordinates than there are
 104  * layers in the current source material then default texture coordinates
 105  * (0.0, 0.0, 1.0, 1.0) are generated.
 106  *
 107  * Since: 1.0
 108  */
 109 void
 110 cogl_rectangle_with_multitexture_coords (float        x1,
 111                                          float        y1,
 112                                          float        x2,
 113                                          float        y2,
 114                                          const float *tex_coords,
 115                                          int         tex_coords_len);
 116
 117 /**
 118  * cogl_rectangles_with_texture_coords:
 119  * @verts: (in) (array) (transfer none): an array of vertices
 120  * @n_rects: number of rectangles to draw
 121  *
 122  * Draws a series of rectangles in the same way that
 123  * cogl_rectangle_with_texture_coords() does. In some situations it can give a
 124  * significant performance boost to use this function rather than
 125  * calling cogl_rectangle_with_texture_coords() separately for each rectangle.
 126  *
 127  * @verts should point to an array of #float<!-- -->s with
 128  * @n_rects * 8 elements. Each group of 8 values corresponds to the
 129  * parameters x1, y1, x2, y2, tx1, ty1, tx2 and ty2 and have the same
 130  * meaning as in cogl_rectangle_with_texture_coords().
 131  *
 132  * Since: 0.8.6
 133  */
 134 void
 135 cogl_rectangles_with_texture_coords (const float *verts,
 136                                      unsigned int n_rects);
 137
 138 /**
 139  * cogl_rectangles:
 140  * @verts: (in) (array) (transfer none): an array of vertices
 141  * @n_rects: number of rectangles to draw
 142  *
 143  * Draws a series of rectangles in the same way that
 144  * cogl_rectangle() does. In some situations it can give a
 145  * significant performance boost to use this function rather than
 146  * calling cogl_rectangle() separately for each rectangle.
 147  *
 148  * @verts should point to an array of #float<!-- -->s with
 149  * @n_rects * 4 elements. Each group of 4 values corresponds to the
 150  * parameters x1, y1, x2, and y2, and have the same
 151  * meaning as in cogl_rectangle().
 152  *
 153  * Since: 1.0
 154  */
 155 void
 156 cogl_rectangles (const float *verts,
 157                  unsigned int n_rects);
 158
 159 /**
 160  * cogl_polygon:
 161  * @vertices: An array of #CoglTextureVertex structs
 162  * @n_vertices: The length of the vertices array
 163  * @use_color: %TRUE if the color member of #CoglTextureVertex should be used
 164  *
 165  * Draws a convex polygon using the current source material to fill / texture
 166  * with according to the texture coordinates passed.
 167  *
 168  * If @use_color is %TRUE then the color will be changed for each vertex using
 169  * the value specified in the color member of #CoglTextureVertex. This can be
 170  * used for example to make the texture fade out by setting the alpha value of
 171  * the color.
 172  *
 173  * All of the texture coordinates must be in the range [0,1] and repeating the
 174  * texture is not supported.
 175  *
 176  * Because of the way this function is implemented it will currently
 177  * only work if either the texture is not sliced or the backend is not
 178  * OpenGL ES and the minifying and magnifying functions are both set
 179  * to COGL_MATERIAL_FILTER_NEAREST.
 180  *
 181  * Since: 1.0
 182  */
 183 void
 184 cogl_polygon (const CoglTextureVertex  *vertices,
 185               unsigned int              n_vertices,
 186               gboolean                  use_color);
 187
 188 G_END_DECLS
 189
 190 #endif /* __COGL_PRIMITIVES_H */