2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY version "1.0.8">
6
<refentry id="cogl-Textures">
8
<refentrytitle role="top_of_page" id="cogl-Textures.top_of_page">Textures</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>COGL Library</refmiscinfo>
14
<refname>Textures</refname>
15
<refpurpose>Fuctions for creating and manipulating textures</refpurpose>
18
<refsynopsisdiv id="cogl-Textures.synopsis" role="synopsis">
19
<title role="synopsis.title">Synopsis</title>
22
<link linkend="CoglTextureVertex">CoglTextureVertex</link>;
23
enum <link linkend="CoglTextureFlags">CoglTextureFlags</link>;
24
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-texture-new-with-size">cogl_texture_new_with_size</link> (<link linkend="guint">guint</link> width,
25
<link linkend="guint">guint</link> height,
26
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
27
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format);
28
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-texture-new-from-file">cogl_texture_new_from_file</link> (const <link linkend="gchar">gchar</link> *filename,
29
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
30
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format,
31
<link linkend="GError">GError</link> **error);
32
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-texture-new-from-data">cogl_texture_new_from_data</link> (<link linkend="guint">guint</link> width,
33
<link linkend="guint">guint</link> height,
34
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
35
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
36
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format,
37
<link linkend="guint">guint</link> rowstride,
38
const <link linkend="guchar">guchar</link> *data);
39
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-texture-new-from-foreign">cogl_texture_new_from_foreign</link> (<link linkend="GLuint">GLuint</link> gl_handle,
40
<link linkend="GLenum">GLenum</link> gl_target,
41
<link linkend="GLuint">GLuint</link> width,
42
<link linkend="GLuint">GLuint</link> height,
43
<link linkend="GLuint">GLuint</link> x_pot_waste,
44
<link linkend="GLuint">GLuint</link> y_pot_waste,
45
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format);
46
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-texture-new-from-bitmap">cogl_texture_new_from_bitmap</link> (<link linkend="CoglHandle">CoglHandle</link> bmp_handle,
47
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
48
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format);
49
<link linkend="gboolean">gboolean</link> <link linkend="cogl-is-texture">cogl_is_texture</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
50
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-texture-ref">cogl_texture_ref</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
51
<link linkend="void">void</link> <link linkend="cogl-texture-unref">cogl_texture_unref</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
53
<link linkend="guint">guint</link> <link linkend="cogl-texture-get-width">cogl_texture_get_width</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
54
<link linkend="guint">guint</link> <link linkend="cogl-texture-get-height">cogl_texture_get_height</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
55
<link linkend="CoglPixelFormat">CoglPixelFormat</link> <link linkend="cogl-texture-get-format">cogl_texture_get_format</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
56
<link linkend="guint">guint</link> <link linkend="cogl-texture-get-rowstride">cogl_texture_get_rowstride</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
57
<link linkend="gint">gint</link> <link linkend="cogl-texture-get-max-waste">cogl_texture_get_max_waste</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
58
<link linkend="gboolean">gboolean</link> <link linkend="cogl-texture-is-sliced">cogl_texture_is_sliced</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
59
<link linkend="gboolean">gboolean</link> <link linkend="cogl-texture-get-gl-texture">cogl_texture_get_gl_texture</link> (<link linkend="CoglHandle">CoglHandle</link> handle,
60
<link linkend="GLuint">GLuint</link> *out_gl_handle,
61
<link linkend="GLenum">GLenum</link> *out_gl_target);
62
<link linkend="gint">gint</link> <link linkend="cogl-texture-get-data">cogl_texture_get_data</link> (<link linkend="CoglHandle">CoglHandle</link> handle,
63
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
64
<link linkend="guint">guint</link> rowstride,
65
<link linkend="guchar">guchar</link> *data);
66
<link linkend="gboolean">gboolean</link> <link linkend="cogl-texture-set-region">cogl_texture_set_region</link> (<link linkend="CoglHandle">CoglHandle</link> handle,
67
<link linkend="gint">gint</link> src_x,
68
<link linkend="gint">gint</link> src_y,
69
<link linkend="gint">gint</link> dst_x,
70
<link linkend="gint">gint</link> dst_y,
71
<link linkend="guint">guint</link> dst_width,
72
<link linkend="guint">guint</link> dst_height,
73
<link linkend="gint">gint</link> width,
74
<link linkend="gint">gint</link> height,
75
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
76
<link linkend="guint">guint</link> rowstride,
77
const <link linkend="guchar">guchar</link> *data);
89
<refsect1 id="cogl-Textures.description" role="desc">
90
<title role="desc.title">Description</title>
92
COGL allows creating and manipulating GL textures using a uniform
93
API that tries to hide all the various complexities of creating,
94
loading and manipulating textures.</para>
99
<refsect1 id="cogl-Textures.details" role="details">
100
<title role="details.title">Details</title>
101
<refsect2 id="CoglTextureVertex" role="struct">
102
<title>CoglTextureVertex</title>
103
<indexterm zone="CoglTextureVertex"><primary sortas="TextureVertex">CoglTextureVertex</primary></indexterm><programlisting>typedef struct {
111
Used to specify vertex information when calling <link linkend="cogl-polygon"><function>cogl_polygon()</function></link></para>
113
</para><variablelist role="struct">
115
<term><link linkend="float">float</link> <structfield>x</structfield>;</term>
116
<listitem><simpara> Model x-coordinate
117
</simpara></listitem>
120
<term><link linkend="float">float</link> <structfield>y</structfield>;</term>
121
<listitem><simpara> Model y-coordinate
122
</simpara></listitem>
125
<term><link linkend="float">float</link> <structfield>z</structfield>;</term>
126
<listitem><simpara> Model z-coordinate
127
</simpara></listitem>
130
<term><link linkend="float">float</link> <structfield>tx</structfield>;</term>
131
<listitem><simpara> Texture x-coordinate
132
</simpara></listitem>
135
<term><link linkend="float">float</link> <structfield>ty</structfield>;</term>
136
<listitem><simpara> Texture y-coordinate
137
</simpara></listitem>
140
<term><link linkend="CoglColor">CoglColor</link> <structfield>color</structfield>;</term>
141
<listitem><simpara> The color to use at this vertex. This is ignored if
142
use_color is <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> when calling <link linkend="cogl-polygon"><function>cogl_polygon()</function></link>
143
</simpara></listitem>
145
</variablelist></refsect2>
146
<refsect2 id="CoglTextureFlags" role="enum" condition="since:1.0">
147
<title>enum CoglTextureFlags</title>
148
<indexterm zone="CoglTextureFlags" role="1.0"><primary sortas="TextureFlags">CoglTextureFlags</primary></indexterm><programlisting>typedef enum {
149
COGL_TEXTURE_NONE = 0,
150
COGL_TEXTURE_NO_AUTO_MIPMAP = 1 << 0,
151
COGL_TEXTURE_NO_SLICING = 1 << 1
155
Flags to pass to the cogl_texture_new_* family of functions.</para>
157
</para><variablelist role="enum">
158
<varlistentry id="COGL-TEXTURE-NONE--CAPS" role="constant">
159
<term><literal>COGL_TEXTURE_NONE</literal></term>
160
<listitem><simpara> No flags specified
161
</simpara></listitem>
163
<varlistentry id="COGL-TEXTURE-NO-AUTO-MIPMAP--CAPS" role="constant">
164
<term><literal>COGL_TEXTURE_NO_AUTO_MIPMAP</literal></term>
165
<listitem><simpara> Disables the automatic generation of
166
the mipmap pyramid from the base level image whenever it is
167
updated. The mipmaps are only generated when the texture is
168
rendered with a mipmap filter so it should be free to leave out
169
this flag when using other filtering modes.
170
</simpara></listitem>
172
<varlistentry id="COGL-TEXTURE-NO-SLICING--CAPS" role="constant">
173
<term><literal>COGL_TEXTURE_NO_SLICING</literal></term>
174
<listitem><simpara> Disables the slicing of the texture
175
</simpara></listitem>
177
</variablelist><para role="since">Since 1.0</para></refsect2>
178
<refsect2 id="cogl-texture-new-with-size" role="function" condition="since:0.8">
179
<title>cogl_texture_new_with_size ()</title>
180
<indexterm zone="cogl-texture-new-with-size" role="0.8"><primary sortas="texture_new_with_size">cogl_texture_new_with_size</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_texture_new_with_size (<link linkend="guint">guint</link> width,
181
<link linkend="guint">guint</link> height,
182
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
183
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format);</programlisting>
185
Creates a new COGL texture with the specified dimensions and pixel format.</para>
187
</para><variablelist role="params">
188
<varlistentry><term><parameter>width</parameter> :</term>
189
<listitem><simpara> width of texture in pixels.
190
</simpara></listitem></varlistentry>
191
<varlistentry><term><parameter>height</parameter> :</term>
192
<listitem><simpara> height of texture in pixels.
193
</simpara></listitem></varlistentry>
194
<varlistentry><term><parameter>flags</parameter> :</term>
195
<listitem><simpara> Optional flags for the texture, or <link linkend="COGL-TEXTURE-NONE--CAPS"><literal>COGL_TEXTURE_NONE</literal></link>
196
</simpara></listitem></varlistentry>
197
<varlistentry><term><parameter>internal_format</parameter> :</term>
198
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> to use for the GPU storage of the
200
</simpara></listitem></varlistentry>
201
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> to the newly created texture or
202
<link linkend="COGL-INVALID-HANDLE--CAPS"><literal>COGL_INVALID_HANDLE</literal></link> on failure
204
</simpara></listitem></varlistentry>
205
</variablelist><para role="since">Since 0.8</para></refsect2>
206
<refsect2 id="cogl-texture-new-from-file" role="function" condition="since:0.8">
207
<title>cogl_texture_new_from_file ()</title>
208
<indexterm zone="cogl-texture-new-from-file" role="0.8"><primary sortas="texture_new_from_file">cogl_texture_new_from_file</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_texture_new_from_file (const <link linkend="gchar">gchar</link> *filename,
209
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
210
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format,
211
<link linkend="GError">GError</link> **error);</programlisting>
213
Creates a COGL texture from an image file.</para>
215
</para><variablelist role="params">
216
<varlistentry><term><parameter>filename</parameter> :</term>
217
<listitem><simpara> the file to load
218
</simpara></listitem></varlistentry>
219
<varlistentry><term><parameter>flags</parameter> :</term>
220
<listitem><simpara> Optional flags for the texture, or <link linkend="COGL-TEXTURE-NONE--CAPS"><literal>COGL_TEXTURE_NONE</literal></link>
221
</simpara></listitem></varlistentry>
222
<varlistentry><term><parameter>internal_format</parameter> :</term>
223
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> to use for the GPU storage of the
224
texture. If COGL_PIXEL_FORMAT_ANY is given then a premultiplied
225
format similar to the format of the source data will be used. The
226
default blending equations of Cogl expect premultiplied color data;
227
the main use of passing a non-premultiplied format here is if you
228
have non-premultiplied source data and are going to adjust the blend
229
mode (see <link linkend="cogl-material-set-blend"><function>cogl_material_set_blend()</function></link>) or use the data for something
230
other than straight blending.
231
</simpara></listitem></varlistentry>
232
<varlistentry><term><parameter>error</parameter> :</term>
233
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
234
</simpara></listitem></varlistentry>
235
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> to the newly created texture or
236
<link linkend="COGL-INVALID-HANDLE--CAPS"><literal>COGL_INVALID_HANDLE</literal></link> on failure
238
</simpara></listitem></varlistentry>
239
</variablelist><para role="since">Since 0.8</para></refsect2>
240
<refsect2 id="cogl-texture-new-from-data" role="function" condition="since:0.8">
241
<title>cogl_texture_new_from_data ()</title>
242
<indexterm zone="cogl-texture-new-from-data" role="0.8"><primary sortas="texture_new_from_data">cogl_texture_new_from_data</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_texture_new_from_data (<link linkend="guint">guint</link> width,
243
<link linkend="guint">guint</link> height,
244
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
245
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
246
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format,
247
<link linkend="guint">guint</link> rowstride,
248
const <link linkend="guchar">guchar</link> *data);</programlisting>
250
Creates a new COGL texture based on data residing in memory.</para>
252
</para><variablelist role="params">
253
<varlistentry><term><parameter>width</parameter> :</term>
254
<listitem><simpara> width of texture in pixels
255
</simpara></listitem></varlistentry>
256
<varlistentry><term><parameter>height</parameter> :</term>
257
<listitem><simpara> height of texture in pixels
258
</simpara></listitem></varlistentry>
259
<varlistentry><term><parameter>flags</parameter> :</term>
260
<listitem><simpara> Optional flags for the texture, or <link linkend="COGL-TEXTURE-NONE--CAPS"><literal>COGL_TEXTURE_NONE</literal></link>
261
</simpara></listitem></varlistentry>
262
<varlistentry><term><parameter>format</parameter> :</term>
263
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> the buffer is stored in in RAM
264
</simpara></listitem></varlistentry>
265
<varlistentry><term><parameter>internal_format</parameter> :</term>
266
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> that will be used for storing
267
the buffer on the GPU. If COGL_PIXEL_FORMAT_ANY is given then a
268
premultiplied format similar to the format of the source data will
269
be used. The default blending equations of Cogl expect premultiplied
270
color data; the main use of passing a non-premultiplied format here
271
is if you have non-premultiplied source data and are going to adjust
272
the blend mode (see <link linkend="cogl-material-set-blend"><function>cogl_material_set_blend()</function></link>) or use the data for
273
something other than straight blending.
274
</simpara></listitem></varlistentry>
275
<varlistentry><term><parameter>rowstride</parameter> :</term>
276
<listitem><simpara> the memory offset in bytes between the starts of
277
scanlines in <parameter>data</parameter>
278
</simpara></listitem></varlistentry>
279
<varlistentry><term><parameter>data</parameter> :</term>
280
<listitem><simpara> pointer the memory region where the source buffer resides
281
</simpara></listitem></varlistentry>
282
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> to the newly created texture or
283
<link linkend="COGL-INVALID-HANDLE--CAPS"><literal>COGL_INVALID_HANDLE</literal></link> on failure
285
</simpara></listitem></varlistentry>
286
</variablelist><para role="since">Since 0.8</para></refsect2>
287
<refsect2 id="cogl-texture-new-from-foreign" role="function" condition="since:0.8">
288
<title>cogl_texture_new_from_foreign ()</title>
289
<indexterm zone="cogl-texture-new-from-foreign" role="0.8"><primary sortas="texture_new_from_foreign">cogl_texture_new_from_foreign</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_texture_new_from_foreign (<link linkend="GLuint">GLuint</link> gl_handle,
290
<link linkend="GLenum">GLenum</link> gl_target,
291
<link linkend="GLuint">GLuint</link> width,
292
<link linkend="GLuint">GLuint</link> height,
293
<link linkend="GLuint">GLuint</link> x_pot_waste,
294
<link linkend="GLuint">GLuint</link> y_pot_waste,
295
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format);</programlisting>
297
Creates a COGL texture based on an existing OpenGL texture; the
298
width, height and format are passed along since it is not possible
299
to query this from a handle with GLES 1.0.</para>
301
</para><variablelist role="params">
302
<varlistentry><term><parameter>gl_handle</parameter> :</term>
303
<listitem><simpara> opengl target type of foreign texture
304
</simpara></listitem></varlistentry>
305
<varlistentry><term><parameter>gl_target</parameter> :</term>
306
<listitem><simpara> opengl handle of foreign texture.
307
</simpara></listitem></varlistentry>
308
<varlistentry><term><parameter>width</parameter> :</term>
309
<listitem><simpara> width of foreign texture
310
</simpara></listitem></varlistentry>
311
<varlistentry><term><parameter>height</parameter> :</term>
312
<listitem><simpara> height of foreign texture.
313
</simpara></listitem></varlistentry>
314
<varlistentry><term><parameter>x_pot_waste</parameter> :</term>
315
<listitem><simpara> maximum horizontal waste.
316
</simpara></listitem></varlistentry>
317
<varlistentry><term><parameter>y_pot_waste</parameter> :</term>
318
<listitem><simpara> maximum vertical waste.
319
</simpara></listitem></varlistentry>
320
<varlistentry><term><parameter>format</parameter> :</term>
321
<listitem><simpara> format of the foreign texture.
322
</simpara></listitem></varlistentry>
323
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> to the newly created texture or
324
<link linkend="COGL-INVALID-HANDLE--CAPS"><literal>COGL_INVALID_HANDLE</literal></link> on failure
326
</simpara></listitem></varlistentry>
327
</variablelist><para role="since">Since 0.8</para></refsect2>
328
<refsect2 id="cogl-texture-new-from-bitmap" role="function" condition="since:1.0">
329
<title>cogl_texture_new_from_bitmap ()</title>
330
<indexterm zone="cogl-texture-new-from-bitmap" role="1.0"><primary sortas="texture_new_from_bitmap">cogl_texture_new_from_bitmap</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_texture_new_from_bitmap (<link linkend="CoglHandle">CoglHandle</link> bmp_handle,
331
<link linkend="CoglTextureFlags">CoglTextureFlags</link> flags,
332
<link linkend="CoglPixelFormat">CoglPixelFormat</link> internal_format);</programlisting>
334
Creates a COGL texture from a CoglBitmap.</para>
336
</para><variablelist role="params">
337
<varlistentry><term><parameter>bmp_handle</parameter> :</term>
338
<listitem><simpara> A CoglBitmap handle
339
</simpara></listitem></varlistentry>
340
<varlistentry><term><parameter>flags</parameter> :</term>
341
<listitem><simpara> Optional flags for the texture, or <link linkend="COGL-TEXTURE-NONE--CAPS"><literal>COGL_TEXTURE_NONE</literal></link>
342
</simpara></listitem></varlistentry>
343
<varlistentry><term><parameter>internal_format</parameter> :</term>
344
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> to use for the GPU storage of the
346
</simpara></listitem></varlistentry>
347
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> to the newly created texture or
348
<link linkend="COGL-INVALID-HANDLE--CAPS"><literal>COGL_INVALID_HANDLE</literal></link> on failure
350
</simpara></listitem></varlistentry>
351
</variablelist><para role="since">Since 1.0</para></refsect2>
352
<refsect2 id="cogl-is-texture" role="function">
353
<title>cogl_is_texture ()</title>
354
<indexterm zone="cogl-is-texture"><primary sortas="is_texture">cogl_is_texture</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_is_texture (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
356
Gets whether the given handle references an existing texture object.</para>
358
</para><variablelist role="params">
359
<varlistentry><term><parameter>handle</parameter> :</term>
360
<listitem><simpara> A CoglHandle
361
</simpara></listitem></varlistentry>
362
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the handle references a texture,
363
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
364
</simpara></listitem></varlistentry>
365
</variablelist></refsect2>
366
<refsect2 id="cogl-texture-ref" role="function">
367
<title>cogl_texture_ref ()</title>
368
<indexterm zone="cogl-texture-ref"><primary sortas="texture_ref">cogl_texture_ref</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_texture_ref (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
370
Increment the reference count for a cogl texture.</para>
372
</para><variablelist role="params">
373
<varlistentry><term><parameter>handle</parameter> :</term>
374
<listitem><simpara> a <parameter>CoglHandle</parameter>.
375
</simpara></listitem></varlistentry>
376
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <parameter>handle</parameter>.
377
</simpara></listitem></varlistentry>
378
</variablelist></refsect2>
379
<refsect2 id="cogl-texture-unref" role="function">
380
<title>cogl_texture_unref ()</title>
381
<indexterm zone="cogl-texture-unref"><primary sortas="texture_unref">cogl_texture_unref</primary></indexterm><programlisting><link linkend="void">void</link> cogl_texture_unref (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
383
Deccrement the reference count for a cogl texture.</para>
385
</para><variablelist role="params">
386
<varlistentry><term><parameter>handle</parameter> :</term>
387
<listitem><simpara> a <parameter>CoglHandle</parameter>.
388
</simpara></listitem></varlistentry>
389
</variablelist></refsect2>
390
<refsect2 id="cogl-texture-get-width" role="function">
391
<title>cogl_texture_get_width ()</title>
392
<indexterm zone="cogl-texture-get-width"><primary sortas="texture_get_width">cogl_texture_get_width</primary></indexterm><programlisting><link linkend="guint">guint</link> cogl_texture_get_width (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
394
Query the width of a cogl texture.</para>
396
</para><variablelist role="params">
397
<varlistentry><term><parameter>handle</parameter> :</term>
398
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
399
</simpara></listitem></varlistentry>
400
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the width of the GPU side texture in pixels:
401
</simpara></listitem></varlistentry>
402
</variablelist></refsect2>
403
<refsect2 id="cogl-texture-get-height" role="function">
404
<title>cogl_texture_get_height ()</title>
405
<indexterm zone="cogl-texture-get-height"><primary sortas="texture_get_height">cogl_texture_get_height</primary></indexterm><programlisting><link linkend="guint">guint</link> cogl_texture_get_height (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
407
Query the height of a cogl texture.</para>
409
</para><variablelist role="params">
410
<varlistentry><term><parameter>handle</parameter> :</term>
411
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
412
</simpara></listitem></varlistentry>
413
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the height of the GPU side texture in pixels:
414
</simpara></listitem></varlistentry>
415
</variablelist></refsect2>
416
<refsect2 id="cogl-texture-get-format" role="function">
417
<title>cogl_texture_get_format ()</title>
418
<indexterm zone="cogl-texture-get-format"><primary sortas="texture_get_format">cogl_texture_get_format</primary></indexterm><programlisting><link linkend="CoglPixelFormat">CoglPixelFormat</link> cogl_texture_get_format (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
420
Query the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> of a cogl texture.</para>
422
</para><variablelist role="params">
423
<varlistentry><term><parameter>handle</parameter> :</term>
424
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
425
</simpara></listitem></varlistentry>
426
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> of the GPU side texture.
427
</simpara></listitem></varlistentry>
428
</variablelist></refsect2>
429
<refsect2 id="cogl-texture-get-rowstride" role="function">
430
<title>cogl_texture_get_rowstride ()</title>
431
<indexterm zone="cogl-texture-get-rowstride"><primary sortas="texture_get_rowstride">cogl_texture_get_rowstride</primary></indexterm><programlisting><link linkend="guint">guint</link> cogl_texture_get_rowstride (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
433
Query the rowstride of a cogl texture.</para>
435
</para><variablelist role="params">
436
<varlistentry><term><parameter>handle</parameter> :</term>
437
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
438
</simpara></listitem></varlistentry>
439
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the offset in bytes between each consequetive row of pixels.
440
</simpara></listitem></varlistentry>
441
</variablelist></refsect2>
442
<refsect2 id="cogl-texture-get-max-waste" role="function">
443
<title>cogl_texture_get_max_waste ()</title>
444
<indexterm zone="cogl-texture-get-max-waste"><primary sortas="texture_get_max_waste">cogl_texture_get_max_waste</primary></indexterm><programlisting><link linkend="gint">gint</link> cogl_texture_get_max_waste (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
446
Query the maximum wasted (unused) pixels in one dimension of a GPU side
449
</para><variablelist role="params">
450
<varlistentry><term><parameter>handle</parameter> :</term>
451
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
452
</simpara></listitem></varlistentry>
453
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the maximum waste.
454
</simpara></listitem></varlistentry>
455
</variablelist></refsect2>
456
<refsect2 id="cogl-texture-is-sliced" role="function">
457
<title>cogl_texture_is_sliced ()</title>
458
<indexterm zone="cogl-texture-is-sliced"><primary sortas="texture_is_sliced">cogl_texture_is_sliced</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_texture_is_sliced (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
460
Query if a texture is sliced (stored as multiple GPU side tecture
463
</para><variablelist role="params">
464
<varlistentry><term><parameter>handle</parameter> :</term>
465
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
466
</simpara></listitem></varlistentry>
467
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the texture is sliced, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the texture
468
is stored as a single GPU texture.
469
</simpara></listitem></varlistentry>
470
</variablelist></refsect2>
471
<refsect2 id="cogl-texture-get-gl-texture" role="function">
472
<title>cogl_texture_get_gl_texture ()</title>
473
<indexterm zone="cogl-texture-get-gl-texture"><primary sortas="texture_get_gl_texture">cogl_texture_get_gl_texture</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_texture_get_gl_texture (<link linkend="CoglHandle">CoglHandle</link> handle,
474
<link linkend="GLuint">GLuint</link> *out_gl_handle,
475
<link linkend="GLenum">GLenum</link> *out_gl_target);</programlisting>
477
Query the GL handles for a GPU side texture through it's <link linkend="CoglHandle"><type>CoglHandle</type></link>,
478
if the texture is spliced the data for the first sub texture will be
481
</para><variablelist role="params">
482
<varlistentry><term><parameter>handle</parameter> :</term>
483
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
484
</simpara></listitem></varlistentry>
485
<varlistentry><term><parameter>out_gl_handle</parameter> :</term>
486
<listitem><simpara>out) (allow-none. <acronym>out</acronym>. <acronym>allow-none</acronym>. </simpara></listitem></varlistentry>
487
<varlistentry><term><parameter>out_gl_target</parameter> :</term>
488
<listitem><simpara>out) (allow-none. <acronym>out</acronym>. <acronym>allow-none</acronym>. </simpara></listitem></varlistentry>
489
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the handle was successfully retrieved <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>
490
if the handle was invalid.
491
</simpara></listitem></varlistentry>
492
</variablelist></refsect2>
493
<refsect2 id="cogl-texture-get-data" role="function">
494
<title>cogl_texture_get_data ()</title>
495
<indexterm zone="cogl-texture-get-data"><primary sortas="texture_get_data">cogl_texture_get_data</primary></indexterm><programlisting><link linkend="gint">gint</link> cogl_texture_get_data (<link linkend="CoglHandle">CoglHandle</link> handle,
496
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
497
<link linkend="guint">guint</link> rowstride,
498
<link linkend="guchar">guchar</link> *data);</programlisting>
500
Copy the pixel data from a cogl texture to system memory.</para>
502
</para><variablelist role="params">
503
<varlistentry><term><parameter>handle</parameter> :</term>
504
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a texture.
505
</simpara></listitem></varlistentry>
506
<varlistentry><term><parameter>format</parameter> :</term>
507
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> to store the texture as.
508
</simpara></listitem></varlistentry>
509
<varlistentry><term><parameter>rowstride</parameter> :</term>
510
<listitem><simpara> the rowstride of <parameter>data</parameter> or retrieved from texture if none is
512
</simpara></listitem></varlistentry>
513
<varlistentry><term><parameter>data</parameter> :</term>
514
<listitem><simpara> memory location to write contents of buffer, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if we're
515
only querying the data size through the return value.
516
</simpara></listitem></varlistentry>
517
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the size of the texture data in bytes (or 0 if the texture
519
</simpara></listitem></varlistentry>
520
</variablelist></refsect2>
521
<refsect2 id="cogl-texture-set-region" role="function">
522
<title>cogl_texture_set_region ()</title>
523
<indexterm zone="cogl-texture-set-region"><primary sortas="texture_set_region">cogl_texture_set_region</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_texture_set_region (<link linkend="CoglHandle">CoglHandle</link> handle,
524
<link linkend="gint">gint</link> src_x,
525
<link linkend="gint">gint</link> src_y,
526
<link linkend="gint">gint</link> dst_x,
527
<link linkend="gint">gint</link> dst_y,
528
<link linkend="guint">guint</link> dst_width,
529
<link linkend="guint">guint</link> dst_height,
530
<link linkend="gint">gint</link> width,
531
<link linkend="gint">gint</link> height,
532
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
533
<link linkend="guint">guint</link> rowstride,
534
const <link linkend="guchar">guchar</link> *data);</programlisting>
536
Sets the pixels in a rectangular subregion of <parameter>handle</parameter> from an in-memory
537
buffer containing pixel data.</para>
539
</para><variablelist role="params">
540
<varlistentry><term><parameter>handle</parameter> :</term>
541
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link>.
542
</simpara></listitem></varlistentry>
543
<varlistentry><term><parameter>src_x</parameter> :</term>
544
<listitem><simpara> upper left coordinate to use from source data.
545
</simpara></listitem></varlistentry>
546
<varlistentry><term><parameter>src_y</parameter> :</term>
547
<listitem><simpara> upper left coordinate to use from source data.
548
</simpara></listitem></varlistentry>
549
<varlistentry><term><parameter>dst_x</parameter> :</term>
550
<listitem><simpara> upper left destination horizontal coordinate.
551
</simpara></listitem></varlistentry>
552
<varlistentry><term><parameter>dst_y</parameter> :</term>
553
<listitem><simpara> upper left destination vertical coordinate.
554
</simpara></listitem></varlistentry>
555
<varlistentry><term><parameter>dst_width</parameter> :</term>
556
<listitem><simpara> width of destination region to write.
557
</simpara></listitem></varlistentry>
558
<varlistentry><term><parameter>dst_height</parameter> :</term>
559
<listitem><simpara> height of destination region to write.
560
</simpara></listitem></varlistentry>
561
<varlistentry><term><parameter>width</parameter> :</term>
562
<listitem><simpara> width of source data buffer.
563
</simpara></listitem></varlistentry>
564
<varlistentry><term><parameter>height</parameter> :</term>
565
<listitem><simpara> height of source data buffer.
566
</simpara></listitem></varlistentry>
567
<varlistentry><term><parameter>format</parameter> :</term>
568
<listitem><simpara> the <link linkend="CoglPixelFormat"><type>CoglPixelFormat</type></link> used in the source buffer.
569
</simpara></listitem></varlistentry>
570
<varlistentry><term><parameter>rowstride</parameter> :</term>
571
<listitem><simpara> rowstride of source buffer (computed from width if none
573
</simpara></listitem></varlistentry>
574
<varlistentry><term><parameter>data</parameter> :</term>
575
<listitem><simpara> the actual pixel data.
576
</simpara></listitem></varlistentry>
577
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the subregion upload was successful, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.
578
</simpara></listitem></varlistentry>
579
</variablelist></refsect2>
added
removed
doc/reference/cogl/xml/cogl-texture.xml
