Line data Source code
1 0 : /*
2 :
3 : OOTexture.h
4 :
5 : Load, track and manage textures. In general, this should be used through an
6 : OOMaterial.
7 :
8 : Note: OOTexture is abstract. The factory methods return instances of
9 : OOConcreteTexture, but special-case implementations are possible.
10 :
11 :
12 : Copyright (C) 2007-2013 Jens Ayton and contributors
13 :
14 : Permission is hereby granted, free of charge, to any person obtaining a copy
15 : of this software and associated documentation files (the "Software"), to deal
16 : in the Software without restriction, including without limitation the rights
17 : to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18 : copies of the Software, and to permit persons to whom the Software is
19 : furnished to do so, subject to the following conditions:
20 :
21 : The above copyright notice and this permission notice shall be included in all
22 : copies or substantial portions of the Software.
23 :
24 : THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25 : IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26 : FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27 : AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28 : LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29 : OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30 : SOFTWARE.
31 :
32 : */
33 :
34 : #import <Foundation/Foundation.h>
35 :
36 : #import "OOOpenGL.h"
37 : #import "OOPixMap.h"
38 : #import "OOWeakReference.h"
39 :
40 : @class OOTextureLoader, OOTextureGenerator;
41 :
42 :
43 0 : enum
44 : {
45 : kOOTextureMinFilterDefault = 0x000000UL,
46 : kOOTextureMinFilterNearest = 0x000001UL,
47 : kOOTextureMinFilterLinear = 0x000002UL,
48 : kOOTextureMinFilterMipMap = 0x000003UL,
49 :
50 : kOOTextureMagFilterNearest = 0x000000UL,
51 : kOOTextureMagFilterLinear = 0x000004UL,
52 :
53 : kOOTextureNoShrink = 0x000010UL,
54 : kOOTextureExtraShrink = 0x000020UL,
55 : kOOTextureRepeatS = 0x000040UL,
56 : kOOTextureRepeatT = 0x000080UL,
57 : kOOTextureAllowRectTexture = 0x000100UL, // Indicates that GL_TEXTURE_RECTANGLE_EXT may be used instead of GL_TEXTURE_2D. See -texCoordsScale for a discussion of rectangle textures.
58 : kOOTextureNoFNFMessage = 0x000200UL, // Don't log file not found error
59 : kOOTextureNeverScale = 0x000400UL, // Don't rescale texture, even if rect textures are not available. This *must not* be used for regular textures, but may be passed to OOTextureLoader when being used for other purposes.
60 : kOOTextureAlphaMask = 0x000800UL, // Single-channel texture should be GL_ALPHA, not GL_LUMINANCE. No effect for multi-channel textures.
61 : kOOTextureAllowCubeMap = 0x001000UL,
62 :
63 : kOOTextureSRGBA = 0x002000UL,
64 :
65 : kOOTextureExtractChannelMask = 0x700000UL,
66 : kOOTextureExtractChannelNone = 0x000000UL,
67 : kOOTextureExtractChannelR = 0x100000UL, // 001
68 : kOOTextureExtractChannelG = 0x300000UL, // 011
69 : kOOTextureExtractChannelB = 0x500000UL, // 101
70 : kOOTextureExtractChannelA = 0x700000UL, // 111
71 :
72 : kOOTextureMinFilterMask = 0x000003UL,
73 : kOOTextureMagFilterMask = 0x000004UL,
74 : kOOTextureFlagsMask = ~(kOOTextureMinFilterMask | kOOTextureMagFilterMask),
75 :
76 : kOOTextureDefaultOptions = kOOTextureMinFilterDefault | kOOTextureMagFilterLinear,
77 :
78 : kOOTextureDefinedFlags = kOOTextureMinFilterMask | kOOTextureMagFilterMask
79 : | kOOTextureNoShrink
80 : | kOOTextureExtraShrink
81 : | kOOTextureAllowRectTexture
82 : | kOOTextureAllowCubeMap
83 : | kOOTextureRepeatS
84 : | kOOTextureRepeatT
85 : | kOOTextureNoFNFMessage
86 : | kOOTextureNeverScale
87 : | kOOTextureAlphaMask
88 : | kOOTextureSRGBA
89 : | kOOTextureExtractChannelMask,
90 :
91 : kOOTextureFlagsAllowedForRectangleTexture =
92 : kOOTextureDefinedFlags & ~(kOOTextureRepeatS | kOOTextureRepeatT),
93 : kOOTextureFlagsAllowedForCubeMap =
94 : kOOTextureDefinedFlags & ~(kOOTextureRepeatS | kOOTextureRepeatT)
95 : };
96 :
97 :
98 0 : typedef uint32_t OOTextureFlags;
99 :
100 :
101 0 : #define kOOTextureDefaultAnisotropy 0.5
102 0 : #define kOOTextureDefaultLODBias -0.25
103 :
104 :
105 0 : enum
106 : {
107 : kOOTextureDataInvalid = kOOPixMapInvalidFormat,
108 :
109 : kOOTextureDataRGBA = kOOPixMapRGBA, // GL_RGBA
110 : kOOTextureDataGrayscale = kOOPixMapGrayscale, // GL_LUMINANCE (or GL_ALPHA with kOOTextureAlphaMask)
111 : kOOTextureDataGrayscaleAlpha = kOOPixMapGrayscaleAlpha // GL_LUMINANCE_ALPHA
112 : };
113 0 : typedef OOPixMapFormat OOTextureDataFormat;
114 :
115 :
116 0 : @interface OOTexture: OOWeakRefObject
117 : {
118 : #ifndef NDEBUG
119 : @protected
120 0 : BOOL _trace;
121 : #endif
122 : }
123 :
124 : /* Load a texture, looking in Textures directories.
125 :
126 : NOTE: anisotropy is normalized to the range [0, 1]. 1 means as high an
127 : anisotropy setting as the hardware supports.
128 :
129 : This method may change; +textureWithConfiguration is generally more
130 : appropriate.
131 : */
132 0 : + (id) textureWithName:(NSString *)name
133 : inFolder:(NSString *)directory
134 : options:(OOTextureFlags)options
135 : anisotropy:(GLfloat)anisotropy
136 : lodBias:(GLfloat)lodBias;
137 :
138 : /* Equivalent to textureWithName:name
139 : inFolder:directory
140 : options:kOOTextureDefaultOptions
141 : anisotropy:kOOTextureDefaultAnisotropy
142 : lodBias:kOOTextureDefaultLODBias
143 : */
144 0 : + (id) textureWithName:(NSString *)name
145 : inFolder:(NSString*)directory;
146 :
147 : /* Load a texure, looking in Textures directories, using configuration
148 : dictionary or name. (That is, configuration may be either an NSDictionary
149 : or an NSString.)
150 :
151 : Supported keys:
152 : name (string, required)
153 : min_filter (string, one of "default", "nearest", "linear", "mipmap")
154 : max_filter (string, one of "default", "nearest", "linear")
155 : noShrink (boolean)
156 : repeat_s (boolean)
157 : repeat_t (boolean)
158 : cube_map (boolean)
159 : anisotropy (real)
160 : texture_LOD_bias (real)
161 : extract_channel (string, one of "r", "g", "b", "a")
162 : */
163 0 : + (id) textureWithConfiguration:(id)configuration;
164 0 : + (id) textureWithConfiguration:(id)configuration extraOptions:(OOTextureFlags)extraOptions;
165 :
166 : /* Return the "null texture", a texture object representing an empty texture.
167 : Applying the null texture is equivalent to calling [OOTexture applyNone].
168 : */
169 0 : + (id) nullTexture;
170 :
171 : /* Load a texture from a generator.
172 : */
173 0 : + (id) textureWithGenerator:(OOTextureGenerator *)generator;
174 :
175 : // Load a texture from a generator with option to force an enqueue
176 0 : + (id) textureWithGenerator:(OOTextureGenerator *)generator enqueue:(BOOL) enqueue;
177 :
178 : /* Bind the texture to the current texture unit.
179 : This will block until loading is completed.
180 : */
181 0 : - (void) apply;
182 :
183 0 : + (void) applyNone;
184 :
185 : /* Ensure texture is loaded. This is required because setting up textures
186 : inside display lists isn't allowed.
187 : */
188 0 : - (void) ensureFinishedLoading;
189 :
190 : /* Check whether a texture has loaded. NOTE: this does not do the setup that
191 : -ensureFinishedLoading does, so -ensureFinishedLoading is still required
192 : before using the texture in a display list.
193 : */
194 0 : - (BOOL) isFinishedLoading;
195 :
196 0 : - (NSString *) cacheKey;
197 :
198 : /* Dimensions in pixels.
199 : This will block until loading is completed.
200 : */
201 0 : - (NSSize) dimensions;
202 :
203 : /* Original file dimensions in pixels.
204 : This will block until loading is completed.
205 : */
206 0 : - (NSSize) originalDimensions;
207 :
208 : /* Check whether texture is mip-mapped.
209 : This will block until loading is completed.
210 : */
211 0 : - (BOOL) isMipMapped;
212 :
213 : /* Create a new pixmap with a copy of the texture data. The caller is
214 : responsible for free()ing the resulting buffer.
215 : */
216 0 : - (OOPixMap) copyPixMapRepresentation;
217 :
218 : /* Identify special texture types.
219 : */
220 0 : - (BOOL) isRectangleTexture;
221 0 : - (BOOL) isCubeMap;
222 :
223 :
224 : /* Dimensions in texture coordinates.
225 :
226 : If kOOTextureAllowRectTexture is set, and GL_EXT_texture_rectangle is
227 : available, textures whose dimensions are not powers of two will be loaded
228 : as rectangle textures. Rectangle textures use unnormalized co-ordinates;
229 : that is, co-oridinates range from 0 to the actual size of the texture
230 : rather than 0 to 1. Thus, for rectangle textures, -texCoordsScale returns
231 : -dimensions (with the required wait for loading) for a rectangle texture.
232 : For non-rectangle textures, (1, 1) is returned without delay. If the
233 : texture has power-of-two dimensions, it will be loaded as a normal
234 : texture.
235 :
236 : Rectangle textures have additional limitations: kOOTextureMinFilterMipMap
237 : is not supported (kOOTextureMinFilterLinear will be used instead), and
238 : kOOTextureRepeatS/kOOTextureRepeatT will be ignored.
239 :
240 : Note that 'rectangle texture' is a misnomer; non-rectangle textures may
241 : be rectangular, as long as their sides are powers of two. Non-power-of-two
242 : textures would be more descriptive, but this phrase is used for the
243 : extension that allows 'normal' textures to have non-power-of-two sides
244 : without additional restrictions. It is intended that OOTexture should
245 : support this in future, but this shouldn’t affect the interface, only
246 : avoid the scaling-to-power-of-two stage.
247 : */
248 0 : - (NSSize) texCoordsScale;
249 :
250 : /* OpenGL texture name.
251 : Not reccomended, but required for legacy TextureStore.
252 : */
253 0 : - (GLint) glTextureName;
254 :
255 : // Forget all cached textures so new texture objects will reload.
256 0 : + (void) clearCache;
257 :
258 : // Called by OOGraphicsResetManager as necessary.
259 0 : + (void) rebindAllTextures;
260 :
261 : #ifndef NDEBUG
262 0 : - (void) setTrace:(BOOL)trace;
263 :
264 0 : + (NSArray *) cachedTexturesByAge;
265 0 : + (NSSet *) allTextures;
266 :
267 0 : - (size_t) dataSize;
268 :
269 0 : - (NSString *) name;
270 : #endif
271 :
272 : @end
273 :
274 :
275 : @interface NSDictionary (OOTextureConveniences)
276 0 : - (NSDictionary *) oo_textureSpecifierForKey:(id)key defaultName:(NSString *)name;
277 : @end
278 :
279 : @interface NSArray (OOTextureConveniences)
280 0 : - (NSDictionary *) oo_textureSpecifierAtIndex:(unsigned)index defaultName:(NSString *)name;
281 : @end
282 :
283 0 : NSDictionary *OOTextureSpecFromObject(id object, NSString *defaultName);
284 :
285 :
286 0 : uint8_t OOTextureComponentsForFormat(OOTextureDataFormat format);
287 :
288 :
289 0 : BOOL OOCubeMapsAvailable(void);
290 :
291 :
292 : /* OOInterpretTextureSpecifier()
293 :
294 : Interpret a texture specifier (string or dictionary). All out parameters
295 : may be NULL.
296 : */
297 0 : BOOL OOInterpretTextureSpecifier(id specifier, NSString **outName, OOTextureFlags *outOptions, float *outAnisotropy, float *outLODBias, BOOL ignoreExtract);
298 :
299 : /* OOMakeTextureSpecifier()
300 :
301 : Create a texture specifier.
302 :
303 : If internal is used, an optimized form unsuitable for serialization may be
304 : used.
305 : */
306 0 : NSDictionary *OOMakeTextureSpecifier(NSString *name, OOTextureFlags options, float anisotropy, float lodBias, BOOL internal);
307 :
308 : /* OOApplyTextureOptionDefaults()
309 :
310 : Replace all default/automatic options with their current default values.
311 : */
312 0 : OOTextureFlags OOApplyTextureOptionDefaults(OOTextureFlags options);
313 :
314 :
315 : // Texture specifier keys.
316 0 : extern NSString * const kOOTextureSpecifierNameKey;
317 0 : extern NSString * const kOOTextureSpecifierSwizzleKey;
318 0 : extern NSString * const kOOTextureSpecifierMinFilterKey;
319 0 : extern NSString * const kOOTextureSpecifierMagFilterKey;
320 0 : extern NSString * const kOOTextureSpecifierNoShrinkKey;
321 0 : extern NSString * const kOOTextureSpecifierExtraShrinkKey;
322 0 : extern NSString * const kOOTextureSpecifierRepeatSKey;
323 0 : extern NSString * const kOOTextureSpecifierRepeatTKey;
324 0 : extern NSString * const kOOTextureSpecifierCubeMapKey;
325 0 : extern NSString * const kOOTextureSpecifierAnisotropyKey;
326 0 : extern NSString * const kOOTextureSpecifierLODBiasKey;
327 :
328 : // Keys not used in texture setup, but put in specific texture specifiers to simplify plists.
329 0 : extern NSString * const kOOTextureSpecifierModulateColorKey;
330 0 : extern NSString * const kOOTextureSpecifierIlluminationModeKey;
331 0 : extern NSString * const kOOTextureSpecifierSelfColorKey;
332 0 : extern NSString * const kOOTextureSpecifierScaleFactorKey;
333 0 : extern NSString * const kOOTextureSpecifierBindingKey;
|
