Panda3D
texturePool.I
1 // Filename: texturePool.I
2 // Created by: drose (26Apr00)
3 // Updated by: fperazzi, PandaSE(29Apr10) (added load_2d_texture_array)
4 //
5 ////////////////////////////////////////////////////////////////////
6 //
7 // PANDA 3D SOFTWARE
8 // Copyright (c) Carnegie Mellon University. All rights reserved.
9 //
10 // All use of this software is subject to the terms of the revised BSD
11 // license. You should have received a copy of this license along
12 // with this source code in a file named "LICENSE."
13 //
14 ////////////////////////////////////////////////////////////////////
15 
16 
17 ////////////////////////////////////////////////////////////////////
18 // Function: TexturePool::has_texture
19 // Access: Published, Static
20 // Description: Returns true if the texture has ever been loaded,
21 // false otherwise.
22 ////////////////////////////////////////////////////////////////////
23 INLINE bool TexturePool::
24 has_texture(const Filename &filename) {
25  return get_global_ptr()->ns_has_texture(filename);
26 }
27 
28 ////////////////////////////////////////////////////////////////////
29 // Function: TexturePool::verify_texture
30 // Access: Published, Static
31 // Description: Loads the given filename up into a texture, if it has
32 // not already been loaded, and returns true to indicate
33 // success, or false to indicate failure. If this
34 // returns true, it is guaranteed that a subsequent call
35 // to load_texture() with the same texture name will
36 // return a valid Texture pointer.
37 ////////////////////////////////////////////////////////////////////
38 INLINE bool TexturePool::
39 verify_texture(const Filename &filename) {
40  return load_texture(filename) != (Texture *)NULL;
41 }
42 
43 ////////////////////////////////////////////////////////////////////
44 // Function: TexturePool::load_texture
45 // Access: Published, Static
46 // Description: Loads the given filename up into a texture, if it has
47 // not already been loaded, and returns the new texture.
48 // If a texture with the same filename was previously
49 // loaded, returns that one instead. If the texture
50 // file cannot be found, returns NULL.
51 //
52 // If read_mipmaps is true, the filename should contain
53 // a hash mark ('#'), which will be filled in with the
54 // mipmap level number; and the texture will be defined
55 // with a series of images, one for each mipmap level.
56 ////////////////////////////////////////////////////////////////////
57 INLINE Texture *TexturePool::
58 load_texture(const Filename &filename, int primary_file_num_channels,
59  bool read_mipmaps, const LoaderOptions &options) {
60  return get_global_ptr()->ns_load_texture(filename, primary_file_num_channels,
61  read_mipmaps, options);
62 }
63 
64 ////////////////////////////////////////////////////////////////////
65 // Function: TexturePool::load_texture
66 // Access: Published, Static
67 // Description: Loads the given filename up into a texture, if it has
68 // not already been loaded, and returns the new texture.
69 // If a texture with the same filename was previously
70 // loaded, returns that one instead. If the texture
71 // file cannot be found, returns NULL.
72 //
73 // If read_mipmaps is true, both filenames should
74 // contain a hash mark ('#'), which will be filled in
75 // with the mipmap level number; and the texture will be
76 // defined with a series of images, two for each mipmap
77 // level.
78 ////////////////////////////////////////////////////////////////////
79 INLINE Texture *TexturePool::
80 load_texture(const Filename &filename, const Filename &alpha_filename,
81  int primary_file_num_channels, int alpha_file_channel,
82  bool read_mipmaps, const LoaderOptions &options) {
83  return get_global_ptr()->ns_load_texture(filename, alpha_filename,
84  primary_file_num_channels,
85  alpha_file_channel,
86  read_mipmaps, options);
87 }
88 
89 ////////////////////////////////////////////////////////////////////
90 // Function: TexturePool::load_3d_texture
91 // Access: Published, Static
92 // Description: Loads a 3-D texture that is specified with a series
93 // of n pages, all numbered in sequence, and beginning
94 // with index 0. The filename should include a sequence
95 // of one or more hash characters ("#") which will be
96 // filled in with the index number of each level.
97 //
98 // If read_mipmaps is true, the filename should contain
99 // an additional hash mark. The first hash mark will be
100 // filled in with the mipmap level number, and the
101 // second with the index number of each 3-d level.
102 ////////////////////////////////////////////////////////////////////
103 INLINE Texture *TexturePool::
104 load_3d_texture(const Filename &filename_pattern, bool read_mipmaps,
105  const LoaderOptions &options) {
106  return get_global_ptr()->ns_load_3d_texture(filename_pattern, read_mipmaps,
107  options);
108 }
109 
110 ////////////////////////////////////////////////////////////////////
111 // Function: TexturePool::load_2d_texture_array
112 // Access: Published, Static
113 // Description: Loads a 2-D texture array that is specified with a series
114 // of n pages, all numbered in sequence, and beginning
115 // with index 0. The filename should include a sequence
116 // of one or more hash characters ("#") which will be
117 // filled in with the index number of each level.
118 //
119 // If read_mipmaps is true, the filename should contain
120 // an additional hash mark. The first hash mark will be
121 // filled in with the mipmap level number, and the
122 // second with the index number of each 2-d level.
123 ////////////////////////////////////////////////////////////////////
124 INLINE Texture *TexturePool::
125 load_2d_texture_array(const Filename &filename_pattern, bool read_mipmaps,
126  const LoaderOptions &options) {
127  return get_global_ptr()->ns_load_2d_texture_array(filename_pattern, read_mipmaps,
128  options);
129 }
130 
131 ////////////////////////////////////////////////////////////////////
132 // Function: TexturePool::load_cube_map
133 // Access: Published, Static
134 // Description: Loads a cube map texture that is specified with a
135 // series of 6 pages, numbered 0 through 5. The
136 // filename should include a sequence of one or more
137 // hash characters ("#") which will be filled in with
138 // the index number of each pagee.
139 //
140 // If read_mipmaps is true, the filename should contain
141 // an additional hash mark. The first hash mark will be
142 // filled in with the mipmap level number, and the
143 // second with the face number, 0 through 5.
144 ////////////////////////////////////////////////////////////////////
145 INLINE Texture *TexturePool::
146 load_cube_map(const Filename &filename_pattern, bool read_mipmaps,
147  const LoaderOptions &options) {
148  return get_global_ptr()->ns_load_cube_map(filename_pattern, read_mipmaps,
149  options);
150 }
151 
152 ////////////////////////////////////////////////////////////////////
153 // Function: TexturePool::get_normalization_cube_map
154 // Access: Published, Static
155 // Description: Returns a standard Texture object that has been
156 // created with
157 // Texture::generate_normalization_cube_map(). This
158 // Texture may be shared by any application code
159 // requiring a normalization cube map. It will be at
160 // least as large as the specified size, though it may
161 // be larger.
162 ////////////////////////////////////////////////////////////////////
163 INLINE Texture *TexturePool::
165  return get_global_ptr()->ns_get_normalization_cube_map(size);
166 }
167 
168 ////////////////////////////////////////////////////////////////////
169 // Function: TexturePool::get_alpha_scale_map
170 // Access: Published, Static
171 // Description: Returns a standard Texture object that has been
172 // created with Texture::generate_alpha_scale_map().
173 //
174 // This Texture object is used internally by Panda to
175 // apply an alpha scale to an object (instead of munging
176 // its vertices) when gsg->get_alpha_scale_via_texture()
177 // returns true.
178 ////////////////////////////////////////////////////////////////////
179 INLINE Texture *TexturePool::
181  return get_global_ptr()->ns_get_alpha_scale_map();
182 }
183 
184 ////////////////////////////////////////////////////////////////////
185 // Function: TexturePool::add_texture
186 // Access: Published, Static
187 // Description: Adds the indicated already-loaded texture to the
188 // pool. The texture must have a filename set for its
189 // name. The texture will always replace any
190 // previously-loaded texture in the pool that had the
191 // same filename.
192 ////////////////////////////////////////////////////////////////////
193 INLINE void TexturePool::
194 add_texture(Texture *texture) {
195  get_global_ptr()->ns_add_texture(texture);
196 }
197 
198 ////////////////////////////////////////////////////////////////////
199 // Function: TexturePool::release_texture
200 // Access: Published, Static
201 // Description: Removes the indicated texture from the pool,
202 // indicating it will never be loaded again; the texture
203 // may then be freed. If this function is never called,
204 // a reference count will be maintained on every texture
205 // every loaded, and textures will never be freed.
206 //
207 // The texture's name should not have been changed
208 // during its lifetime, or this function may fail to
209 // locate it in the pool.
210 ////////////////////////////////////////////////////////////////////
211 INLINE void TexturePool::
213  get_global_ptr()->ns_release_texture(texture);
214 }
215 
216 ////////////////////////////////////////////////////////////////////
217 // Function: TexturePool::release_all_textures
218 // Access: Published, Static
219 // Description: Releases all textures in the pool and restores the
220 // pool to the empty state.
221 ////////////////////////////////////////////////////////////////////
222 INLINE void TexturePool::
224  get_global_ptr()->ns_release_all_textures();
225 }
226 
227 ////////////////////////////////////////////////////////////////////
228 // Function: TexturePool::rehash
229 // Access: Published, Static
230 // Description: Should be called when the model-path changes, to blow
231 // away the cache of texture pathnames found along the
232 // model-path.
233 ////////////////////////////////////////////////////////////////////
234 INLINE void TexturePool::
236  get_global_ptr()->_relpath_lookup.clear();
237 }
238 
239 ////////////////////////////////////////////////////////////////////
240 // Function: TexturePool::garbage_collect
241 // Access: Published, Static
242 // Description: Releases only those textures in the pool that have a
243 // reference count of exactly 1; i.e. only those
244 // textures that are not being used outside of the pool.
245 // Returns the number of textures released.
246 ////////////////////////////////////////////////////////////////////
247 INLINE int TexturePool::
249  return get_global_ptr()->ns_garbage_collect();
250 }
251 
252 ////////////////////////////////////////////////////////////////////
253 // Function: TexturePool::list_contents
254 // Access: Published, Static
255 // Description: Lists the contents of the texture pool to the
256 // indicated output stream.
257 ////////////////////////////////////////////////////////////////////
258 INLINE void TexturePool::
259 list_contents(ostream &out) {
260  get_global_ptr()->ns_list_contents(out);
261 }
262 
263 ////////////////////////////////////////////////////////////////////
264 // Function: TexturePool::list_contents
265 // Access: Published, Static
266 // Description: Lists the contents of the texture pool to cout
267 ////////////////////////////////////////////////////////////////////
268 INLINE void TexturePool::
270  get_global_ptr()->ns_list_contents(cout);
271 }
272 
273 ////////////////////////////////////////////////////////////////////
274 // Function: TexturePool::find_texture
275 // Access: Published, Static
276 // Description: Returns the first texture found in the pool that
277 // matches the indicated name (which may contain
278 // wildcards). Returns the texture if it is found, or
279 // NULL if it is not.
280 ////////////////////////////////////////////////////////////////////
281 INLINE Texture *TexturePool::
282 find_texture(const string &name) {
283  return get_global_ptr()->ns_find_texture(name);
284 }
285 
286 ////////////////////////////////////////////////////////////////////
287 // Function: TexturePool::find_all_textures
288 // Access: Published, Static
289 // Description: Returns the set of all textures found in the pool
290 // that match the indicated name (which may contain
291 // wildcards).
292 ////////////////////////////////////////////////////////////////////
294 find_all_textures(const string &name) {
295  return get_global_ptr()->ns_find_all_textures(name);
296 }
297 
298 ////////////////////////////////////////////////////////////////////
299 // Function: TexturePool::set_fake_texture_image
300 // Access: Published, Static
301 // Description: Sets a bogus filename that will be loaded in lieu of
302 // any textures requested from this point on.
303 ////////////////////////////////////////////////////////////////////
304 INLINE void TexturePool::
306  get_global_ptr()->_fake_texture_image = filename;
307 }
308 
309 ////////////////////////////////////////////////////////////////////
310 // Function: TexturePool::clear_fake_texture_image
311 // Access: Published, Static
312 // Description: Restores normal behavior of loading the textures
313 // actually requested.
314 ////////////////////////////////////////////////////////////////////
315 INLINE void TexturePool::
317  set_fake_texture_image(string());
318 }
319 
320 ////////////////////////////////////////////////////////////////////
321 // Function: TexturePool::has_fake_texture_image
322 // Access: Published, Static
323 // Description: Returns true if fake_texture_image mode has been
324 // enabled, false if we are in the normal mode.
325 ////////////////////////////////////////////////////////////////////
326 INLINE bool TexturePool::
328  return !get_fake_texture_image().empty();
329 }
330 
331 ////////////////////////////////////////////////////////////////////
332 // Function: TexturePool::get_fake_texture_image
333 // Access: Published, Static
334 // Description: Returns the filename that was specified with a
335 // previous call to set_fake_texture_image().
336 ////////////////////////////////////////////////////////////////////
337 INLINE const Filename &TexturePool::
339  return get_global_ptr()->_fake_texture_image;
340 }
341 
342 ////////////////////////////////////////////////////////////////////
343 // Function: TexturePool::make_texture
344 // Access: Published, Static
345 // Description: Creates a new Texture object of the appropriate type
346 // for the indicated filename extension, according to
347 // the types that have been registered via
348 // register_texture_type().
349 ////////////////////////////////////////////////////////////////////
350 PT(Texture) TexturePool::
351 make_texture(const string &extension) {
352  return get_global_ptr()->ns_make_texture(extension);
353 }
static void list_contents()
Lists the contents of the texture pool to cout.
Definition: texturePool.I:269
static void clear_fake_texture_image()
Restores normal behavior of loading the textures actually requested.
Definition: texturePool.I:316
static Texture * load_cube_map(const Filename &filename_pattern, bool read_mipmaps=false, const LoaderOptions &options=LoaderOptions())
Loads a cube map texture that is specified with a series of 6 pages, numbered 0 through 5...
Definition: texturePool.I:146
static int garbage_collect()
Releases only those textures in the pool that have a reference count of exactly 1; i...
Definition: texturePool.I:248
Specifies parameters that may be passed to the loader.
Definition: loaderOptions.h:26
static Texture * find_texture(const string &name)
Returns the first texture found in the pool that matches the indicated name (which may contain wildca...
Definition: texturePool.I:282
static void release_texture(Texture *texture)
Removes the indicated texture from the pool, indicating it will never be loaded again; the texture ma...
Definition: texturePool.I:212
Represents a texture object, which is typically a single 2-d image but may also represent a 1-d or 3-...
Definition: texture.h:75
static void rehash()
Should be called when the model-path changes, to blow away the cache of texture pathnames found along...
Definition: texturePool.I:235
static bool has_fake_texture_image()
Returns true if fake_texture_image mode has been enabled, false if we are in the normal mode...
Definition: texturePool.I:327
static bool verify_texture(const Filename &filename)
Loads the given filename up into a texture, if it has not already been loaded, and returns true to in...
Definition: texturePool.I:39
static TextureCollection find_all_textures(const string &name="*")
Returns the set of all textures found in the pool that match the indicated name (which may contain wi...
Definition: texturePool.I:294
static Texture * get_alpha_scale_map()
Returns a standard Texture object that has been created with Texture::generate_alpha_scale_map().
Definition: texturePool.I:180
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:44
static const Filename & get_fake_texture_image()
Returns the filename that was specified with a previous call to set_fake_texture_image().
Definition: texturePool.I:338
static void set_fake_texture_image(const Filename &filename)
Sets a bogus filename that will be loaded in lieu of any textures requested from this point on...
Definition: texturePool.I:305
static Texture * get_normalization_cube_map(int size)
Returns a standard Texture object that has been created with Texture::generate_normalization_cube_map...
Definition: texturePool.I:164
static bool has_texture(const Filename &filename)
Returns true if the texture has ever been loaded, false otherwise.
Definition: texturePool.I:24
Manages a list of Texture objects, as returned by TexturePool::find_all_textures().
static Texture * load_texture(const Filename &filename, int primary_file_num_channels=0, bool read_mipmaps=false, const LoaderOptions &options=LoaderOptions())
Loads the given filename up into a texture, if it has not already been loaded, and returns the new te...
Definition: texturePool.I:58
static TexturePool * get_global_ptr()
Initializes and/or returns the global pointer to the one TexturePool object in the system...
static void add_texture(Texture *texture)
Adds the indicated already-loaded texture to the pool.
Definition: texturePool.I:194
static void release_all_textures()
Releases all textures in the pool and restores the pool to the empty state.
Definition: texturePool.I:223
static Texture * load_3d_texture(const Filename &filename_pattern, bool read_mipmaps=false, const LoaderOptions &options=LoaderOptions())
Loads a 3-D texture that is specified with a series of n pages, all numbered in sequence, and beginning with index 0.
Definition: texturePool.I:104
static Texture * load_2d_texture_array(const Filename &filename_pattern, bool read_mipmaps=false, const LoaderOptions &options=LoaderOptions())
Loads a 2-D texture array that is specified with a series of n pages, all numbered in sequence...
Definition: texturePool.I:125