doc/reference/cogl-2.0-experimental/html/cogl-2.0-experimental-3D-textures.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>3D textures</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="Cogl 2.0 Reference Manual">
   8 <link rel="up" href="cogl-textures.html" title="Textures">
   9 <link rel="prev" href="cogl-2.0-experimental-2D-textures.html" title="2D textures">
  10 <link rel="next" href="cogl-2.0-experimental-Rectangle-textures-(non-normalized-coordinates).html" title="Rectangle textures (non-normalized coordinates)">
  11 <meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="cogl-2.0-experimental-2D-textures.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="cogl-textures.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">Cogl 2.0 Reference Manual</th>
  21 <td><a accesskey="n" href="cogl-2.0-experimental-Rectangle-textures-(non-normalized-coordinates).html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#cogl-2.0-experimental-3D-textures.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#cogl-2.0-experimental-3D-textures.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="cogl-2.0-experimental-3D-textures"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="cogl-2.0-experimental-3D-textures.top_of_page"></a>3D textures</span></h2>
  34 <p>3D textures — Fuctions for creating and manipulating 3D textures</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="cogl-2.0-experimental-3D-textures.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">                    <a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D">CoglTexture3D</a>;
  41 <a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="returnvalue">CoglTexture3D</span></a> *     <a class="link" href="cogl-2.0-experimental-3D-textures.html#cogl-texture-3d-new-with-size" title="cogl_texture_3d_new_with_size ()">cogl_texture_3d_new_with_size</a>       (<em class="parameter"><code><span class="type">CoglContext</span> *context</code></em>,
  42                                                          <em class="parameter"><code><span class="type">int</span> width</code></em>,
  43                                                          <em class="parameter"><code><span class="type">int</span> height</code></em>,
  44                                                          <em class="parameter"><code><span class="type">int</span> depth</code></em>,
  45                                                          <em class="parameter"><code><a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> internal_format</code></em>,
  46                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
  47 <a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="returnvalue">CoglTexture3D</span></a> *     <a class="link" href="cogl-2.0-experimental-3D-textures.html#cogl-texture-3d-new-from-data" title="cogl_texture_3d_new_from_data ()">cogl_texture_3d_new_from_data</a>       (<em class="parameter"><code><span class="type">CoglContext</span> *context</code></em>,
  48                                                          <em class="parameter"><code><span class="type">int</span> width</code></em>,
  49                                                          <em class="parameter"><code><span class="type">int</span> height</code></em>,
  50                                                          <em class="parameter"><code><span class="type">int</span> depth</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> format</code></em>,
  52                                                          <em class="parameter"><code><a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> internal_format</code></em>,
  53                                                          <em class="parameter"><code><span class="type">int</span> rowstride</code></em>,
  54                                                          <em class="parameter"><code><span class="type">int</span> image_stride</code></em>,
  55                                                          <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint8"><span class="type">guint8</span></a> *data</code></em>,
  56                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
  57 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="cogl-2.0-experimental-3D-textures.html#cogl-is-texture-3d" title="cogl_is_texture_3d ()">cogl_is_texture_3d</a>                  (<em class="parameter"><code><span class="type">void</span> *object</code></em>);
  58 </pre>
  59 </div>
  60 <div class="refsect1">
  61 <a name="cogl-2.0-experimental-3D-textures.description"></a><h2>Description</h2>
  62 <p>
  63 These functions allow 3D textures to be used. 3D textures can be
  64 thought of as layers of 2D images arranged into a cuboid
  65 shape. When choosing a texel from the texture, Cogl will take into
  66 account the 'r' texture coordinate to select one of the images.
  67 </p>
  68 </div>
  69 <div class="refsect1">
  70 <a name="cogl-2.0-experimental-3D-textures.details"></a><h2>Details</h2>
  71 <div class="refsect2">
  72 <a name="CoglTexture3D"></a><h3>CoglTexture3D</h3>
  73 <pre class="programlisting">typedef struct _CoglTexture3D CoglTexture3D;</pre>
  74 </div>
  75 <hr>
  76 <div class="refsect2">
  77 <a name="cogl-texture-3d-new-with-size"></a><h3>cogl_texture_3d_new_with_size ()</h3>
  78 <pre class="programlisting"><a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="returnvalue">CoglTexture3D</span></a> *     cogl_texture_3d_new_with_size       (<em class="parameter"><code><span class="type">CoglContext</span> *context</code></em>,
  79                                                          <em class="parameter"><code><span class="type">int</span> width</code></em>,
  80                                                          <em class="parameter"><code><span class="type">int</span> height</code></em>,
  81                                                          <em class="parameter"><code><span class="type">int</span> depth</code></em>,
  82                                                          <em class="parameter"><code><a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> internal_format</code></em>,
  83                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
  84 <p>
  85 Creates a new Cogl 3D texture with the specified dimensions and
  86 pixel format.
  87 </p>
  88 <p>
  89 Note that this function will throw a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> if
  90 <a href="../cogl/cogl-General-API.html#COGL-FEATURE-TEXTURE-3D:CAPS"><code class="literal">COGL_FEATURE_TEXTURE_3D</code></a> is not advertised. It can also fail if the
  91 requested dimensions are not supported by the GPU.
  92 </p>
  93 <div class="variablelist"><table border="0">
  94 <col align="left" valign="top">
  95 <tbody>
  96 <tr>
  97 <td><p><span class="term"><em class="parameter"><code>context</code></em> :</span></p></td>
  98 <td>a <span class="type">CoglContext</span>
  99 </td>
 100 </tr>
 101 <tr>
 102 <td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
 103 <td>width of the texture in pixels.</td>
 104 </tr>
 105 <tr>
 106 <td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
 107 <td>height of the texture in pixels.</td>
 108 </tr>
 109 <tr>
 110 <td><p><span class="term"><em class="parameter"><code>depth</code></em> :</span></p></td>
 111 <td>depth of the texture in pixels.</td>
 112 </tr>
 113 <tr>
 114 <td><p><span class="term"><em class="parameter"><code>internal_format</code></em> :</span></p></td>
 115 <td>the <a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> to use for the GPU
 116 storage of the texture.</td>
 117 </tr>
 118 <tr>
 119 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 120 <td>A GError return location.</td>
 121 </tr>
 122 <tr>
 123 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 124 <td>a new <a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="type">CoglTexture3D</span></a> object or
 125 <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on failure and an exception will be returned
 126 in <em class="parameter"><code>error</code></em>.</td>
 127 </tr>
 128 </tbody>
 129 </table></div>
 130 <p class="since">Since 1.10</p>
 131 <p class="stability">Stability Level: Unstable</p>
 132 </div>
 133 <hr>
 134 <div class="refsect2">
 135 <a name="cogl-texture-3d-new-from-data"></a><h3>cogl_texture_3d_new_from_data ()</h3>
 136 <pre class="programlisting"><a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="returnvalue">CoglTexture3D</span></a> *     cogl_texture_3d_new_from_data       (<em class="parameter"><code><span class="type">CoglContext</span> *context</code></em>,
 137                                                          <em class="parameter"><code><span class="type">int</span> width</code></em>,
 138                                                          <em class="parameter"><code><span class="type">int</span> height</code></em>,
 139                                                          <em class="parameter"><code><span class="type">int</span> depth</code></em>,
 140                                                          <em class="parameter"><code><a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> format</code></em>,
 141                                                          <em class="parameter"><code><a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> internal_format</code></em>,
 142                                                          <em class="parameter"><code><span class="type">int</span> rowstride</code></em>,
 143                                                          <em class="parameter"><code><span class="type">int</span> image_stride</code></em>,
 144                                                          <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint8"><span class="type">guint8</span></a> *data</code></em>,
 145                                                          <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 146 <p>
 147 Creates a new 3D texture and initializes it with <em class="parameter"><code>data</code></em>. The data is
 148 assumed to be packed array of <em class="parameter"><code>depth</code></em> images. There can be padding
 149 between the images using <em class="parameter"><code>image_stride</code></em>.
 150 </p>
 151 <p>
 152 Note that this function will throw a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> if
 153 <a href="../cogl/cogl-General-API.html#COGL-FEATURE-TEXTURE-3D:CAPS"><code class="literal">COGL_FEATURE_TEXTURE_3D</code></a> is not advertised. It can also fail if the
 154 requested dimensions are not supported by the GPU.
 155 </p>
 156 <div class="variablelist"><table border="0">
 157 <col align="left" valign="top">
 158 <tbody>
 159 <tr>
 160 <td><p><span class="term"><em class="parameter"><code>context</code></em> :</span></p></td>
 161 <td>a <span class="type">CoglContext</span>
 162 </td>
 163 </tr>
 164 <tr>
 165 <td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
 166 <td>width of the texture in pixels.</td>
 167 </tr>
 168 <tr>
 169 <td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
 170 <td>height of the texture in pixels.</td>
 171 </tr>
 172 <tr>
 173 <td><p><span class="term"><em class="parameter"><code>depth</code></em> :</span></p></td>
 174 <td>depth of the texture in pixels.</td>
 175 </tr>
 176 <tr>
 177 <td><p><span class="term"><em class="parameter"><code>format</code></em> :</span></p></td>
 178 <td>the <a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> the buffer is stored in in RAM</td>
 179 </tr>
 180 <tr>
 181 <td><p><span class="term"><em class="parameter"><code>internal_format</code></em> :</span></p></td>
 182 <td>the <a class="link" href="cogl-2.0-experimental-Common-Types.html#CoglPixelFormat" title="enum CoglPixelFormat"><span class="type">CoglPixelFormat</span></a> that will be used for storing
 183 the buffer on the GPU. If COGL_PIXEL_FORMAT_ANY is given then a
 184 premultiplied format similar to the format of the source data will
 185 be used. The default blending equations of Cogl expect premultiplied
 186 color data; the main use of passing a non-premultiplied format here
 187 is if you have non-premultiplied source data and are going to adjust
 188 the blend mode (see <a href="../cogl/cogl-Materials.html#cogl-material-set-blend"><code class="function">cogl_material_set_blend()</code></a>) or use the data for
 189 something other than straight blending.</td>
 190 </tr>
 191 <tr>
 192 <td><p><span class="term"><em class="parameter"><code>rowstride</code></em> :</span></p></td>
 193 <td>the memory offset in bytes between the starts of
 194 scanlines in <em class="parameter"><code>data</code></em> or 0 to infer it from the width and format</td>
 195 </tr>
 196 <tr>
 197 <td><p><span class="term"><em class="parameter"><code>image_stride</code></em> :</span></p></td>
 198 <td>the number of bytes from one image to the next. This
 199 can be used to add padding between the images in a similar way
 200 that the rowstride can be used to add padding between
 201 rows. Alternatively 0 can be passed to infer the <em class="parameter"><code>image_stride</code></em>
 202 from the <em class="parameter"><code>height</code></em>.</td>
 203 </tr>
 204 <tr>
 205 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 206 <td>pointer the memory region where the source buffer resides</td>
 207 </tr>
 208 <tr>
 209 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 210 <td>A GError return location.</td>
 211 </tr>
 212 <tr>
 213 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 214 <td>the newly created <a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="type">CoglTexture3D</span></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if
 215 there was an error an an exception will be returned
 216 through <em class="parameter"><code>error</code></em>.</td>
 217 </tr>
 218 </tbody>
 219 </table></div>
 220 <p class="since">Since 1.10</p>
 221 <p class="stability">Stability Level: Unstable</p>
 222 </div>
 223 <hr>
 224 <div class="refsect2">
 225 <a name="cogl-is-texture-3d"></a><h3>cogl_is_texture_3d ()</h3>
 226 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a>            cogl_is_texture_3d                  (<em class="parameter"><code><span class="type">void</span> *object</code></em>);</pre>
 227 <p>
 228 Checks whether the given object references a <a class="link" href="cogl-2.0-experimental-3D-textures.html#CoglTexture3D" title="CoglTexture3D"><span class="type">CoglTexture3D</span></a>
 229 </p>
 230 <div class="variablelist"><table border="0">
 231 <col align="left" valign="top">
 232 <tbody>
 233 <tr>
 234 <td><p><span class="term"><em class="parameter"><code>object</code></em> :</span></p></td>
 235 <td>a <a class="link" href="cogl-2.0-experimental-The-Object-Interface.html#CoglObject" title="CoglObject"><span class="type">CoglObject</span></a>
 236 </td>
 237 </tr>
 238 <tr>
 239 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 240 <td>
 241 <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the passed object represents a 3D texture
 242 and <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</td>
 243 </tr>
 244 </tbody>
 245 </table></div>
 246 <p class="since">Since 1.4</p>
 247 <p class="stability">Stability Level: Unstable</p>
 248 </div>
 249 </div>
 250 </div>
 251 <div class="footer">
 252 <hr>
 253           Generated by GTK-Doc V1.18.1</div>
 254 </body>
 255 </html>