4
* A Low Level GPU Graphics and Utilities API
6
* Copyright (C) 2011 Intel Corporation.
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:
16
* The above copyright notice and this permission notice shall be
17
* included in all copies or substantial portions of the Software.
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
31
#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
32
#error "Only <cogl/cogl.h> can be included directly."
35
#ifndef __COGL_META_TEXTURE_H__
36
#define __COGL_META_TEXTURE_H__
38
#include <cogl/cogl-pipeline-layer-state.h>
43
* SECTION:cogl-meta-texture
44
* @short_description: Interface for high-level textures built from
45
* low-level textures like #CoglTexture2D and
48
* Cogl helps to make it easy to deal with high level textures such
49
* as #CoglAtlasTexture<!-- -->s, #CoglSubTexture<!-- -->s,
50
* #CoglTexturePixmapX11 textures and #CoglTexture2DSliced textures
53
* A #CoglMetaTexture is a texture that might internally be
54
* represented by one or more low-level #CoglTexture<!-- -->s
55
* such as #CoglTexture2D or #CoglTexture3D. These low-level textures
56
* are the only ones that a GPU really understands but because
57
* applications often want more high-level texture abstractions
58
* (such as storing multiple textures inside one larger "atlas"
59
* texture) it's desirable to be able to deal with these
60
* using a common interface.
62
* For example the GPU is not able to automatically handle repeating a
63
* texture that is part of a larger atlas texture but if you use
64
* %COGL_PIPELINE_WRAP_MODE_REPEAT with an atlas texture when drawing
65
* with cogl_rectangle() you should see that it "Just Works™" - at
66
* least if you don't use multi-texturing. The reason this works is
67
* because cogl_rectangle() internally understands the #CoglMetaTexture
68
* interface and is able to manually resolve the low-level textures
69
* using this interface and by making multiple draw calls it can
70
* emulate the texture repeat modes.
72
* Cogl doesn't aim to pretend that meta-textures are just like real
73
* textures because it would get extremely complex to try and emulate
74
* low-level GPU semantics transparently for these textures. The low
75
* level drawing APIs of Cogl, such as cogl_primitive_draw() don't
76
* actually know anything about the #CoglMetaTexture interface and its
77
* the developer's responsibility to resolve all textures referenced
78
* by a #CoglPipeline to low-level textures before drawing.
80
* If you want to develop custom primitive APIs like
81
* cogl_framebuffer_draw_rectangle() and you want to support drawing
82
* with #CoglAtlasTexture<!-- -->s or #CoglSubTexture<!-- -->s for
83
* example, then you will need to use this #CoglMetaTexture interface
84
* to be able to resolve high-level textures into low-level textures
85
* before drawing with Cogl's low-level drawing APIs such as
86
* cogl_primitive_draw().
88
* <note>Most developers won't need to use this interface directly
89
* but still it is worth understanding the distinction between
90
* low-level and meta textures because you may find other references
91
* in the documentation that detail limitations of using
92
* meta-textures.</note>
95
#ifdef __COGL_H_INSIDE__
96
/* For the public C api we typedef interface types as void to avoid needing
97
* lots of casting in code and instead we will rely on runtime type checking
98
* for these objects. */
99
typedef void CoglMetaTexture;
101
typedef struct _CoglMetaTexture CoglMetaTexture;
102
#define COGL_META_TEXTURE(X) ((CoglMetaTexture *)X)
106
* CoglMetaTextureCallback:
107
* @sub_texture: A low-level #CoglTexture making up part of a
109
* @sub_texture_coords: A float 4-tuple ordered like
110
* (tx1,ty1,tx2,ty2) defining what region of the
111
* current @sub_texture maps to a sub-region of a
112
* #CoglMetaTexture. (tx1,ty1) is the top-left
113
* sub-region coordinate and (tx2,ty2) is the
114
* bottom-right. These are low-level texture
116
* @meta_coords: A float 4-tuple ordered like (tx1,ty1,tx2,ty2)
117
* defining what sub-region of a #CoglMetaTexture this
118
* low-level @sub_texture maps too. (tx1,ty1) is
119
* the top-left sub-region coordinate and (tx2,ty2) is
120
* the bottom-right. These are high-level meta-texture
122
* @user_data: A private pointer passed to
123
* cogl_meta_texture_foreach_in_region().
125
* A callback used with cogl_meta_texture_foreach_in_region() to
126
* retrieve details of all the low-level #CoglTexture<!-- -->s that
127
* make up a given #CoglMetaTexture.
130
* Stability: unstable
132
typedef void (*CoglMetaTextureCallback) (CoglTexture *sub_texture,
133
const float *sub_texture_coords,
134
const float *meta_coords,
138
* cogl_meta_texture_foreach_in_region:
139
* @meta_texture: An object implementing the #CoglMetaTexture
141
* @tx_1: The top-left x coordinate of the region to iterate
142
* @ty_1: The top-left y coordinate of the region to iterate
143
* @tx_2: The bottom-right x coordinate of the region to iterate
144
* @ty_2: The bottom-right y coordinate of the region to iterate
145
* @wrap_s: The wrap mode for the x-axis
146
* @wrap_t: The wrap mode for the y-axis
147
* @callback: A #CoglMetaTextureCallback pointer to be called
148
* for each low-level texture within the specified region.
149
* @user_data: A private pointer that is passed to @callback.
151
* Allows you to manually iterate the low-level textures that define a
152
* given region of a high-level #CoglMetaTexture.
154
* For example cogl_texture_2d_sliced_new_with_size() can be used to
155
* create a meta texture that may slice a large image into multiple,
156
* smaller power-of-two sized textures. These high level textures are
157
* not directly understood by a GPU and so this API must be used to
158
* manually resolve the underlying textures for drawing.
160
* All high level textures (#CoglAtlasTexture, #CoglSubTexture,
161
* #CoglTexturePixmapX11, and #CoglTexture2DSliced) can be handled
162
* consistently using this interface which greately simplifies
163
* implementing primitives that support all texture types.
165
* For example if you use the cogl_rectangle() API then Cogl will
166
* internally use this API to resolve the low level textures of any
167
* meta textures you have associated with CoglPipeline layers.
169
* <note>The low level drawing APIs such as cogl_primitive_draw()
170
* don't understand the #CoglMetaTexture interface and so it is your
171
* responsibility to use this API to resolve all CoglPipeline textures
172
* into low-level textures before drawing.</note>
174
* For each low-level texture that makes up part of the given region
175
* of the @meta_texture, @callback is called specifying how the
176
* low-level texture maps to the original region.
179
* Stability: unstable
182
cogl_meta_texture_foreach_in_region (CoglMetaTexture *meta_texture,
187
CoglPipelineWrapMode wrap_s,
188
CoglPipelineWrapMode wrap_t,
189
CoglMetaTextureCallback callback,
194
#endif /* __COGL_META_TEXTURE_H__ */
added
removed
cogl/cogl/cogl-meta-texture.h
