cogl/cogl-texture-3d.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
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  *
  23  * Authors:
  24  *   Neil Roberts <neil@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_TEXTURE_3D_H
  32 #define __COGL_TEXTURE_3D_H
  33
  34 #include <glib.h>
  35
  36 G_BEGIN_DECLS
  37
  38 /**
  39  * SECTION:cogl-texture-3d
  40  * @short_description: Fuctions for creating and manipulating 3D textures
  41  *
  42  * These functions allow 3D textures to be used. 3D textures can be
  43  * thought of as layers of 2D images arranged into a cuboid
  44  * shape. When choosing a texel from the texture, Cogl will take into
  45  * account the 'r' texture coordinate to select one of the images.
  46  */
  47
  48 typedef struct _CoglTexture3D CoglTexture3D;
  49
  50 #define COGL_TEXTURE_3D(X) ((CoglTexture3D *)X)
  51
  52 /**
  53  * cogl_texture_3d_new_with_size:
  54  * @context: a #CoglContext
  55  * @width: width of the texture in pixels.
  56  * @height: height of the texture in pixels.
  57  * @depth: depth of the texture in pixels.
  58  * @internal_format: the #CoglPixelFormat to use for the GPU
  59  *    storage of the texture.
  60  * @error: A GError return location.
  61  *
  62  * Creates a new Cogl 3D texture with the specified dimensions and
  63  * pixel format.
  64  *
  65  * Note that this function will throw a #GError if
  66  * %COGL_FEATURE_TEXTURE_3D is not advertised. It can also fail if the
  67  * requested dimensions are not supported by the GPU.
  68  *
  69  * Return value: a new #CoglTexture3D object or
  70  *               %NULL on failure and an exception will be returned
  71  *               in @error.
  72  * Since: 1.10
  73  * Stability: Unstable
  74  */
  75 CoglTexture3D *
  76 cogl_texture_3d_new_with_size (CoglContext *context,
  77                                int width,
  78                                int height,
  79                                int depth,
  80                                CoglPixelFormat  internal_format,
  81                                GError **error);
  82
  83 /**
  84  * cogl_texture_3d_new_from_data:
  85  * @context: a #CoglContext
  86  * @width: width of the texture in pixels.
  87  * @height: height of the texture in pixels.
  88  * @depth: depth of the texture in pixels.
  89  * @format: the #CoglPixelFormat the buffer is stored in in RAM
  90  * @internal_format: the #CoglPixelFormat that will be used for storing
  91  *    the buffer on the GPU. If COGL_PIXEL_FORMAT_ANY is given then a
  92  *    premultiplied format similar to the format of the source data will
  93  *    be used. The default blending equations of Cogl expect premultiplied
  94  *    color data; the main use of passing a non-premultiplied format here
  95  *    is if you have non-premultiplied source data and are going to adjust
  96  *    the blend mode (see cogl_material_set_blend()) or use the data for
  97  *    something other than straight blending.
  98  * @rowstride: the memory offset in bytes between the starts of
  99  *    scanlines in @data or 0 to infer it from the width and format
 100  * @image_stride: the number of bytes from one image to the next. This
 101  *    can be used to add padding between the images in a similar way
 102  *    that the rowstride can be used to add padding between
 103  *    rows. Alternatively 0 can be passed to infer the @image_stride
 104  *    from the @height.
 105  * @data: pointer the memory region where the source buffer resides
 106  * @error: A GError return location.
 107  *
 108  * Creates a new 3D texture and initializes it with @data. The data is
 109  * assumed to be packed array of @depth images. There can be padding
 110  * between the images using @image_stride.
 111  *
 112  * Note that this function will throw a #GError if
 113  * %COGL_FEATURE_TEXTURE_3D is not advertised. It can also fail if the
 114  * requested dimensions are not supported by the GPU.
 115  *
 116  * Return value: the newly created #CoglTexture3D or %NULL if
 117  *               there was an error an an exception will be returned
 118  *               through @error.
 119  * Since: 1.10
 120  * Stability: Unstable
 121  */
 122 CoglTexture3D *
 123 cogl_texture_3d_new_from_data (CoglContext *context,
 124                                int width,
 125                                int height,
 126                                int depth,
 127                                CoglPixelFormat format,
 128                                CoglPixelFormat internal_format,
 129                                int rowstride,
 130                                int image_stride,
 131                                const guint8 *data,
 132                                GError **error);
 133
 134 /**
 135  * cogl_is_texture_3d:
 136  * @object: a #CoglObject
 137  *
 138  * Checks whether the given object references a #CoglTexture3D
 139  *
 140  * Return value: %TRUE if the passed object represents a 3D texture
 141  *   and %FALSE otherwise
 142  *
 143  * Since: 1.4
 144  * Stability: Unstable
 145  */
 146 gboolean
 147 cogl_is_texture_3d (void *object);
 148
 149 G_END_DECLS
 150
 151 #endif /* __COGL_TEXTURE_3D_H */