1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
/*
* Cogl
*
* An object oriented GL/GLES Abstraction/Utility Layer
*
* Copyright (C) 2011,2013 Intel Corporation.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see
* <http://www.gnu.org/licenses/>.
*
*
* Authors:
* Robert Bragg <robert@linux.intel.com>
*/
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif
#ifndef __COGL_TEXTURE_2D_H
#define __COGL_TEXTURE_2D_H
#include "cogl-context.h"
#include "cogl-bitmap.h"
COGL_BEGIN_DECLS
/**
* SECTION:cogl-texture-2d
* @short_description: Functions for creating and manipulating 2D textures
*
* These functions allow low-level 2D textures to be allocated. These
* differ from sliced textures for example which may internally be
* made up of multiple 2D textures, or atlas textures where Cogl must
* internally modify user texture coordinates before they can be used
* by the GPU.
*
* You should be aware that many GPUs only support power of two sizes
* for #CoglTexture2D textures. You can check support for non power of
* two textures by checking for the %COGL_FEATURE_ID_TEXTURE_NPOT feature
* via cogl_has_feature().
*/
typedef struct _CoglTexture2D CoglTexture2D;
#define COGL_TEXTURE_2D(X) ((CoglTexture2D *)X)
#ifdef COGL_HAS_GTYPE_SUPPORT
/**
* cogl_texture_2d_get_gtype:
*
* Returns: a #GType that can be used with the GLib type system.
*/
GType cogl_texture_2d_get_gtype (void);
#endif
/**
* cogl_is_texture_2d:
* @object: A #CoglObject
*
* Gets whether the given object references an existing #CoglTexture2D
* object.
*
* Return value: %TRUE if the object references a #CoglTexture2D,
* %FALSE otherwise
*/
CoglBool
cogl_is_texture_2d (void *object);
/**
* cogl_texture_2d_new_with_size:
* @ctx: A #CoglContext
* @width: Width of the texture to allocate
* @height: Height of the texture to allocate
*
* Creates a low-level #CoglTexture2D texture with a given @width and
* @height that your GPU can texture from directly.
*
* The storage for the texture is not allocated before this function
* returns. You can call cogl_texture_allocate() to explicitly
* allocate the underlying storage or preferably let Cogl
* automatically allocate storage lazily when it may know more about
* how the texture is being used and can optimize how it is allocated.
*
* The texture is still configurable until it has been allocated so
* for example you can influence the internal format of the texture
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
* <note>Many GPUs only support power of two sizes for #CoglTexture2D
* textures. You can check support for non power of two textures by
* checking for the %COGL_FEATURE_ID_TEXTURE_NPOT feature via
* cogl_has_feature().</note>
*
* Returns: (transfer full): A new #CoglTexture2D object with no storage yet allocated.
*
* Since: 2.0
*/
CoglTexture2D *
cogl_texture_2d_new_with_size (CoglContext *ctx,
int width,
int height);
/**
* cogl_texture_2d_new_from_file:
* @ctx: A #CoglContext
* @filename: the file to load
* @error: A #CoglError to catch exceptional errors or %NULL
*
* Creates a low-level #CoglTexture2D texture from an image file.
*
* The storage for the texture is not allocated before this function
* returns. You can call cogl_texture_allocate() to explicitly
* allocate the underlying storage or preferably let Cogl
* automatically allocate storage lazily when it may know more about
* how the texture is being used and can optimize how it is allocated.
*
* The texture is still configurable until it has been allocated so
* for example you can influence the internal format of the texture
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
* <note>Many GPUs only support power of two sizes for #CoglTexture2D
* textures. You can check support for non power of two textures by
* checking for the %COGL_FEATURE_ID_TEXTURE_NPOT feature via
* cogl_has_feature().</note>
*
* Return value: (transfer full): A newly created #CoglTexture2D or %NULL on failure
* and @error will be updated.
*
* Since: 1.16
*/
CoglTexture2D *
cogl_texture_2d_new_from_file (CoglContext *ctx,
const char *filename,
CoglError **error);
/**
* cogl_texture_2d_new_from_data:
* @ctx: A #CoglContext
* @width: width of texture in pixels
* @height: height of texture in pixels
* @format: the #CoglPixelFormat the buffer is stored in in RAM
* @rowstride: the memory offset in bytes between the starts of
* scanlines in @data. A value of 0 will make Cogl automatically
* calculate @rowstride from @width and @format.
* @data: pointer the memory region where the source buffer resides
* @error: A #CoglError for exceptions
*
* Creates a low-level #CoglTexture2D texture based on data residing
* in memory.
*
* <note>This api will always immediately allocate GPU memory for the
* texture and upload the given data so that the @data pointer does
* not need to remain valid once this function returns. This means it
* is not possible to configure the texture before it is allocated. If
* you do need to configure the texture before allocation (to specify
* constraints on the internal format for example) then you can
* instead create a #CoglBitmap for your data and use
* cogl_texture_2d_new_from_bitmap() or use
* cogl_texture_2d_new_with_size() and then upload data using
* cogl_texture_set_data()</note>
*
* <note>Many GPUs only support power of two sizes for #CoglTexture2D
* textures. You can check support for non power of two textures by
* checking for the %COGL_FEATURE_ID_TEXTURE_NPOT feature via
* cogl_has_feature().</note>
*
* Returns: (transfer full): A newly allocated #CoglTexture2D, or if
* the size is not supported (because it is too large or a
* non-power-of-two size that the hardware doesn't support)
* it will return %NULL and set @error.
*
* Since: 2.0
*/
CoglTexture2D *
cogl_texture_2d_new_from_data (CoglContext *ctx,
int width,
int height,
CoglPixelFormat format,
int rowstride,
const uint8_t *data,
CoglError **error);
/**
* cogl_texture_2d_new_from_bitmap:
* @bitmap: A #CoglBitmap
*
* Creates a low-level #CoglTexture2D texture based on data residing
* in a #CoglBitmap.
*
* The storage for the texture is not allocated before this function
* returns. You can call cogl_texture_allocate() to explicitly
* allocate the underlying storage or preferably let Cogl
* automatically allocate storage lazily when it may know more about
* how the texture is being used and can optimize how it is allocated.
*
* The texture is still configurable until it has been allocated so
* for example you can influence the internal format of the texture
* using cogl_texture_set_components() and
* cogl_texture_set_premultiplied().
*
* <note>Many GPUs only support power of two sizes for #CoglTexture2D
* textures. You can check support for non power of two textures by
* checking for the %COGL_FEATURE_ID_TEXTURE_NPOT feature via
* cogl_has_feature().</note>
*
* Returns: (transfer full): A newly allocated #CoglTexture2D
*
* Since: 2.0
* Stability: unstable
*/
CoglTexture2D *
cogl_texture_2d_new_from_bitmap (CoglBitmap *bitmap);
COGL_END_DECLS
#endif /* __COGL_TEXTURE_2D_H */
|
