1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2011 Intel Corporation. 7 * 8 * Permission is hereby granted, free of charge, to any person 9 * obtaining a copy of this software and associated documentation 10 * files (the "Software"), to deal in the Software without 11 * restriction, including without limitation the rights to use, copy, 12 * modify, merge, publish, distribute, sublicense, and/or sell copies 13 * of the Software, and to permit persons to whom the Software is 14 * furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 23 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 24 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 25 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 26 * SOFTWARE. 27 * 28 * 29 * Authors: 30 * Robert Bragg <robert@linux.intel.com> 31 */ 32 33 #ifndef __COGL_TEXURE_RECTANGLE_H 34 #define __COGL_TEXURE_RECTANGLE_H 35 36 #include "cogl-context.h" 37 38 COGL_BEGIN_DECLS 39 40 /** 41 * SECTION:cogl-texture-rectangle 42 * @short_description: Functions for creating and manipulating rectangle 43 * textures for use with non-normalized coordinates. 44 * 45 * These functions allow low-level "rectangle" textures to be allocated. 46 * These textures are never constrained to power-of-two sizes but they 47 * also don't support having a mipmap and can only be wrapped with 48 * %COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE. 49 * 50 * The most notable difference between rectangle textures and 2D 51 * textures is that rectangle textures are sampled using un-normalized 52 * texture coordinates, so instead of using coordinates (0,0) and 53 * (1,1) to map to the top-left and bottom right corners of the 54 * texture you would instead use (0,0) and (width,height). 55 * 56 * The use of non-normalized coordinates can be particularly 57 * convenient when writing glsl shaders that use a texture as a lookup 58 * table since you don't need to upload separate uniforms to map 59 * normalized coordinates to texels. 60 * 61 * If you want to sample from a rectangle texture from GLSL you should 62 * use the sampler2DRect sampler type. 63 * 64 * Applications wanting to use #CoglTextureRectangle should first check 65 * for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature using 66 * cogl_has_feature(). 67 */ 68 69 typedef struct _CoglTextureRectangle CoglTextureRectangle; 70 #define COGL_TEXTURE_RECTANGLE(X) ((CoglTextureRectangle *)X) 71 72 #ifdef COGL_HAS_GTYPE_SUPPORT 73 /** 74 * cogl_texture_rectangle_get_gtype: 75 * 76 * Returns: a #GType that can be used with the GLib type system. 77 */ 78 GType cogl_texture_rectangle_get_gtype (void); 79 #endif 80 81 /** 82 * cogl_is_texture_rectangle: 83 * @object: A #CoglObject 84 * 85 * Gets whether the given object references an existing 86 * #CoglTextureRectangle object. 87 * 88 * Return value: %TRUE if the object references a 89 * #CoglTextureRectangle, %FALSE otherwise. 90 */ 91 CoglBool 92 cogl_is_texture_rectangle (void *object); 93 94 /** 95 * cogl_texture_rectangle_new_with_size: 96 * @ctx: A #CoglContext pointer 97 * @width: The texture width to allocate 98 * @height: The texture height to allocate 99 * 100 * Creates a new #CoglTextureRectangle texture with a given @width, 101 * and @height. This texture is a low-level texture that the GPU can 102 * sample from directly unlike high-level textures such as 103 * #CoglTexture2DSliced and #CoglAtlasTexture. 104 * 105 * <note>Unlike for #CoglTexture2D textures, coordinates for 106 * #CoglTextureRectangle textures should not be normalized. So instead 107 * of using the coordinate (1, 1) to sample the bottom right corner of 108 * a rectangle texture you would use (@width, @height) where @width 109 * and @height are the width and height of the texture.</note> 110 * 111 * <note>If you want to sample from a rectangle texture from GLSL you 112 * should use the sampler2DRect sampler type.</note> 113 * 114 * <note>Applications wanting to use #CoglTextureRectangle should 115 * first check for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature 116 * using cogl_has_feature().</note> 117 * 118 * The storage for the texture is not allocated before this function 119 * returns. You can call cogl_texture_allocate() to explicitly 120 * allocate the underlying storage or preferably let Cogl 121 * automatically allocate storage lazily when it may know more about 122 * how the texture is going to be used and can optimize how it is 123 * allocated. 124 * 125 * Returns value: (transfer full): A pointer to a new #CoglTextureRectangle 126 * object with no storage allocated yet. 127 * 128 * Since: 1.10 129 * Stability: unstable 130 */ 131 CoglTextureRectangle * 132 cogl_texture_rectangle_new_with_size (CoglContext *ctx, 133 int width, 134 int height); 135 136 /** 137 * cogl_texture_rectangle_new_from_bitmap: 138 * @bitmap: A #CoglBitmap 139 * 140 * Allocates a new #CoglTextureRectangle texture which will be 141 * initialized with the pixel data from @bitmap. This texture is a 142 * low-level texture that the GPU can sample from directly unlike 143 * high-level textures such as #CoglTexture2DSliced and 144 * #CoglAtlasTexture. 145 * 146 * <note>Unlike for #CoglTexture2D textures, coordinates for 147 * #CoglTextureRectangle textures should not be normalized. So instead 148 * of using the coordinate (1, 1) to sample the bottom right corner of 149 * a rectangle texture you would use (@width, @height) where @width 150 * and @height are the width and height of the texture.</note> 151 * 152 * <note>If you want to sample from a rectangle texture from GLSL you 153 * should use the sampler2DRect sampler type.</note> 154 * 155 * <note>Applications wanting to use #CoglTextureRectangle should 156 * first check for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature 157 * using cogl_has_feature().</note> 158 * 159 * The storage for the texture is not allocated before this function 160 * returns. You can call cogl_texture_allocate() to explicitly 161 * allocate the underlying storage or preferably let Cogl 162 * automatically allocate storage lazily when it may know more about 163 * how the texture is going to be used and can optimize how it is 164 * allocated. 165 * 166 * Return value: (transfer full): A pointer to a new 167 * #CoglTextureRectangle texture. 168 * Since: 2.0 169 * Stability: unstable 170 */ 171 CoglTextureRectangle * 172 cogl_texture_rectangle_new_from_bitmap (CoglBitmap *bitmap); 173 174 /** 175 * cogl_texture_rectangle_new_from_foreign: 176 * @ctx: A #CoglContext 177 * @gl_handle: A GL handle for a GL_TEXTURE_RECTANGLE texture object 178 * @width: Width of the foreign GL texture 179 * @height: Height of the foreign GL texture 180 * @format: The format of the texture 181 * 182 * Wraps an existing GL_TEXTURE_RECTANGLE texture object as a 183 * #CoglTextureRectangle. This can be used for integrating Cogl with 184 * software using OpenGL directly. 185 * 186 * <note>Unlike for #CoglTexture2D textures, coordinates for 187 * #CoglTextureRectangle textures should not be normalized. So instead 188 * of using the coordinate (1, 1) to sample the bottom right corner of 189 * a rectangle texture you would use (@width, @height) where @width 190 * and @height are the width and height of the texture.</note> 191 * 192 * <note>The results are undefined for passing an invalid @gl_handle 193 * or if @width or @height don't have the correct texture 194 * geometry.</note> 195 * 196 * <note>If you want to sample from a rectangle texture from GLSL you 197 * should use the sampler2DRect sampler type.</note> 198 * 199 * <note>Applications wanting to use #CoglTextureRectangle should 200 * first check for the %COGL_FEATURE_ID_TEXTURE_RECTANGLE feature 201 * using cogl_has_feature().</note> 202 * 203 * The texture is still configurable until it has been allocated so 204 * for example you can declare whether the texture is premultiplied 205 * with cogl_texture_set_premultiplied(). 206 * 207 * Return value: (transfer full): A new #CoglTextureRectangle texture 208 */ 209 CoglTextureRectangle * 210 cogl_texture_rectangle_new_from_foreign (CoglContext *ctx, 211 unsigned int gl_handle, 212 int width, 213 int height, 214 CoglPixelFormat format); 215 216 COGL_END_DECLS 217 218 #endif /* __COGL_TEXURE_RECTANGLE_H */ 219