cogl/cogl-texture-rectangle.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2011 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
  20  * <http://www.gnu.org/licenses/>.
  21  *
  22  *
  23  * Authors:
  24  *   Robert Bragg <robert@linux.intel.com>
  25  */
  26
  27 #ifndef __COGL_TEXURE_RECTANGLE_H
  28 #define __COGL_TEXURE_RECTANGLE_H
  29
  30 #include "cogl-context.h"
  31
  32 G_BEGIN_DECLS
  33
  34 /**
  35  * SECTION:cogl-texture-rectangle
  36  * @short_description: Functions for creating and manipulating rectangle
  37  *                     textures for use with non-normalized coordinates.
  38  *
  39  * These functions allow low-level "rectangle" textures to be allocated.
  40  * These textures are never constrained to power-of-two sizes but they
  41  * also don't support having a mipmap and can only be wrapped with
  42  * %COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE.
  43  *
  44  * The most notable difference between rectangle textures and 2D
  45  * textures is that rectangle textures are sampled using un-normalized
  46  * texture coordinates, so instead of using coordinates (0,0) and
  47  * (1,1) to map to the top-left and bottom right corners of the
  48  * texture you would instead use (0,0) and (width,height).
  49  *
  50  * The use of non-normalized coordinates can be particularly
  51  * convenient when writing glsl shaders that use a texture as a lookup
  52  * table since you don't need to upload separate uniforms to map
  53  * normalized coordinates to texels.
  54  *
  55  * If you want to sample from a rectangle texture from GLSL you should
  56  * use the sampler2DRect sampler type.
  57  *
  58  * Applications wanting to use #CoglTextureRectangle should first check
  59  * for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature using
  60  * cogl_has_feature().
  61  */
  62
  63 typedef struct _CoglTextureRectangle CoglTextureRectangle;
  64 #define COGL_TEXTURE_RECTANGLE(X) ((CoglTextureRectangle *)X)
  65
  66 #define cogl_is_texture_rectangle cogl_is_texture_rectangle_EXP
  67 /**
  68  * cogl_is_texture_rectangle:
  69  * @object: A #CoglObject
  70  *
  71  * Gets whether the given object references an existing
  72  * #CoglTextureRectangle object.
  73  *
  74  * Return value: %TRUE if the object references a
  75  *               #CoglTextureRectangle, %FALSE otherwise.
  76  */
  77 gboolean
  78 cogl_is_texture_rectangle (void *object);
  79
  80 #define cogl_texture_rectangle_new_with_size \
  81   cogl_texture_rectangle_new_with_size_EXP
  82 /**
  83  * cogl_texture_rectangle_new_with_size:
  84  * @context: A #CoglContext pointer
  85  * @width: The texture width to allocate
  86  * @height: The texture height to allocate
  87  * @internal_format: The desired internal texture format
  88  * @error: An optional GError pointer for reporting exceptions
  89  *
  90  * Allocates a new #CoglRectangle texture with a given @width, @height
  91  * and @internal_format. This texture is a low-level texture that
  92  * the GPU can sample from directly unlike high-level textures such
  93  * as #CoglTexture2DSliced and #CoglAtlasTexture.
  94  *
  95  * <note>If you want to sample from a rectangle texture from GLSL you
  96  * should use the sampler2DRect sampler type.</note>
  97  *
  98  * <note>Applications wanting to use #CoglTextureRectangle should
  99  * first check for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature
 100  * using cogl_has_feature().</note>
 101  *
 102  * Returns: A pointer to a newly allocated #CoglRectangle texture
 103  *          or if the size was too large or there wasn't enough memory
 104  *          %NULL is returned and @error set.
 105  *
 106  * Since: 1.10
 107  * Stability: unstable
 108  */
 109 CoglTextureRectangle *
 110 cogl_texture_rectangle_new_with_size (CoglContext *ctx,
 111                                       int width,
 112                                       int height,
 113                                       CoglPixelFormat internal_format,
 114                                       GError **error);
 115
 116 G_END_DECLS
 117
 118 #endif /* __COGL_TEXURE_RECTANGLE_H */