Panda3D

texturePool.I

00001 // Filename: texturePool.I
00002 // Created by:  drose (26Apr00)
00003 // Updated by: fperazzi, PandaSE(29Apr10) (added load_2d_texture_array)
00004 //
00005 ////////////////////////////////////////////////////////////////////
00006 //
00007 // PANDA 3D SOFTWARE
00008 // Copyright (c) Carnegie Mellon University.  All rights reserved.
00009 //
00010 // All use of this software is subject to the terms of the revised BSD
00011 // license.  You should have received a copy of this license along
00012 // with this source code in a file named "LICENSE."
00013 //
00014 ////////////////////////////////////////////////////////////////////
00015 
00016 
00017 ////////////////////////////////////////////////////////////////////
00018 //     Function: TexturePool::has_texture
00019 //       Access: Published, Static
00020 //  Description: Returns true if the texture has ever been loaded,
00021 //               false otherwise.
00022 ////////////////////////////////////////////////////////////////////
00023 INLINE bool TexturePool::
00024 has_texture(const Filename &filename) {
00025   return get_global_ptr()->ns_has_texture(filename);
00026 }
00027 
00028 ////////////////////////////////////////////////////////////////////
00029 //     Function: TexturePool::verify_texture
00030 //       Access: Published, Static
00031 //  Description: Loads the given filename up into a texture, if it has
00032 //               not already been loaded, and returns true to indicate
00033 //               success, or false to indicate failure.  If this
00034 //               returns true, it is guaranteed that a subsequent call
00035 //               to load_texture() with the same texture name will
00036 //               return a valid Texture pointer.
00037 ////////////////////////////////////////////////////////////////////
00038 INLINE bool TexturePool::
00039 verify_texture(const Filename &filename) {
00040   return load_texture(filename) != (Texture *)NULL;
00041 }
00042 
00043 ////////////////////////////////////////////////////////////////////
00044 //     Function: TexturePool::load_texture
00045 //       Access: Published, Static
00046 //  Description: Loads the given filename up into a texture, if it has
00047 //               not already been loaded, and returns the new texture.
00048 //               If a texture with the same filename was previously
00049 //               loaded, returns that one instead.  If the texture
00050 //               file cannot be found, returns NULL.
00051 //
00052 //               If read_mipmaps is true, the filename should contain
00053 //               a hash mark ('#'), which will be filled in with the
00054 //               mipmap level number; and the texture will be defined
00055 //               with a series of images, one for each mipmap level.
00056 ////////////////////////////////////////////////////////////////////
00057 INLINE Texture *TexturePool::
00058 load_texture(const Filename &filename, int primary_file_num_channels,
00059              bool read_mipmaps, const LoaderOptions &options) {
00060   return get_global_ptr()->ns_load_texture(filename, primary_file_num_channels,
00061                                            read_mipmaps, options);
00062 }
00063 
00064 ////////////////////////////////////////////////////////////////////
00065 //     Function: TexturePool::load_texture
00066 //       Access: Published, Static
00067 //  Description: Loads the given filename up into a texture, if it has
00068 //               not already been loaded, and returns the new texture.
00069 //               If a texture with the same filename was previously
00070 //               loaded, returns that one instead.  If the texture
00071 //               file cannot be found, returns NULL.
00072 //
00073 //               If read_mipmaps is true, both filenames should
00074 //               contain a hash mark ('#'), which will be filled in
00075 //               with the mipmap level number; and the texture will be
00076 //               defined with a series of images, two for each mipmap
00077 //               level.
00078 ////////////////////////////////////////////////////////////////////
00079 INLINE Texture *TexturePool::
00080 load_texture(const Filename &filename, const Filename &alpha_filename,
00081              int primary_file_num_channels, int alpha_file_channel,
00082              bool read_mipmaps, const LoaderOptions &options) {
00083   return get_global_ptr()->ns_load_texture(filename, alpha_filename, 
00084                                            primary_file_num_channels,
00085                                            alpha_file_channel,
00086                                            read_mipmaps, options);
00087 }
00088 
00089 ////////////////////////////////////////////////////////////////////
00090 //     Function: TexturePool::load_3d_texture
00091 //       Access: Published, Static
00092 //  Description: Loads a 3-D texture that is specified with a series
00093 //               of n pages, all numbered in sequence, and beginning
00094 //               with index 0.  The filename should include a sequence
00095 //               of one or more hash characters ("#") which will be
00096 //               filled in with the index number of each level.
00097 //
00098 //               If read_mipmaps is true, the filename should contain
00099 //               an additional hash mark.  The first hash mark will be
00100 //               filled in with the mipmap level number, and the
00101 //               second with the index number of each 3-d level.
00102 ////////////////////////////////////////////////////////////////////
00103 INLINE Texture *TexturePool::
00104 load_3d_texture(const Filename &filename_pattern, bool read_mipmaps, 
00105                 const LoaderOptions &options) {
00106   return get_global_ptr()->ns_load_3d_texture(filename_pattern, read_mipmaps, 
00107                                               options);
00108 }
00109 
00110 ////////////////////////////////////////////////////////////////////
00111 //     Function: TexturePool::load_2d_texture_array
00112 //       Access: Published, Static
00113 //  Description: Loads a 2-D texture array that is specified with a series
00114 //               of n pages, all numbered in sequence, and beginning
00115 //               with index 0.  The filename should include a sequence
00116 //               of one or more hash characters ("#") which will be
00117 //               filled in with the index number of each level.
00118 //
00119 //               If read_mipmaps is true, the filename should contain
00120 //               an additional hash mark.  The first hash mark will be
00121 //               filled in with the mipmap level number, and the
00122 //               second with the index number of each 2-d level.
00123 ////////////////////////////////////////////////////////////////////
00124 INLINE Texture *TexturePool::
00125 load_2d_texture_array(const Filename &filename_pattern, bool read_mipmaps, 
00126                 const LoaderOptions &options) {
00127   return get_global_ptr()->ns_load_2d_texture_array(filename_pattern, read_mipmaps, 
00128                                                     options);
00129 }
00130 
00131 ////////////////////////////////////////////////////////////////////
00132 //     Function: TexturePool::load_cube_map
00133 //       Access: Published, Static
00134 //  Description: Loads a cube map texture that is specified with a
00135 //               series of 6 pages, numbered 0 through 5.  The
00136 //               filename should include a sequence of one or more
00137 //               hash characters ("#") which will be filled in with
00138 //               the index number of each pagee.
00139 //
00140 //               If read_mipmaps is true, the filename should contain
00141 //               an additional hash mark.  The first hash mark will be
00142 //               filled in with the mipmap level number, and the
00143 //               second with the face number, 0 through 5.
00144 ////////////////////////////////////////////////////////////////////
00145 INLINE Texture *TexturePool::
00146 load_cube_map(const Filename &filename_pattern, bool read_mipmaps, 
00147               const LoaderOptions &options) {
00148   return get_global_ptr()->ns_load_cube_map(filename_pattern, read_mipmaps, 
00149                                             options);
00150 }
00151 
00152 ////////////////////////////////////////////////////////////////////
00153 //     Function: TexturePool::get_normalization_cube_map
00154 //       Access: Published, Static
00155 //  Description: Returns a standard Texture object that has been
00156 //               created with
00157 //               Texture::generate_normalization_cube_map().  This
00158 //               Texture may be shared by any application code
00159 //               requiring a normalization cube map.  It will be at
00160 //               least as large as the specified size, though it may
00161 //               be larger.
00162 ////////////////////////////////////////////////////////////////////
00163 INLINE Texture *TexturePool::
00164 get_normalization_cube_map(int size) {
00165   return get_global_ptr()->ns_get_normalization_cube_map(size);
00166 }
00167 
00168 ////////////////////////////////////////////////////////////////////
00169 //     Function: TexturePool::get_alpha_scale_map
00170 //       Access: Published, Static
00171 //  Description: Returns a standard Texture object that has been
00172 //               created with Texture::generate_alpha_scale_map().
00173 //
00174 //               This Texture object is used internally by Panda to
00175 //               apply an alpha scale to an object (instead of munging
00176 //               its vertices) when gsg->get_alpha_scale_via_texture()
00177 //               returns true.
00178 ////////////////////////////////////////////////////////////////////
00179 INLINE Texture *TexturePool::
00180 get_alpha_scale_map() {
00181   return get_global_ptr()->ns_get_alpha_scale_map();
00182 }
00183 
00184 ////////////////////////////////////////////////////////////////////
00185 //     Function: TexturePool::add_texture
00186 //       Access: Published, Static
00187 //  Description: Adds the indicated already-loaded texture to the
00188 //               pool.  The texture must have a filename set for its
00189 //               name.  The texture will always replace any
00190 //               previously-loaded texture in the pool that had the
00191 //               same filename.
00192 ////////////////////////////////////////////////////////////////////
00193 INLINE void TexturePool::
00194 add_texture(Texture *texture) {
00195   get_global_ptr()->ns_add_texture(texture);
00196 }
00197 
00198 ////////////////////////////////////////////////////////////////////
00199 //     Function: TexturePool::release_texture
00200 //       Access: Published, Static
00201 //  Description: Removes the indicated texture from the pool,
00202 //               indicating it will never be loaded again; the texture
00203 //               may then be freed.  If this function is never called,
00204 //               a reference count will be maintained on every texture
00205 //               every loaded, and textures will never be freed.
00206 //
00207 //               The texture's name should not have been changed
00208 //               during its lifetime, or this function may fail to
00209 //               locate it in the pool.
00210 ////////////////////////////////////////////////////////////////////
00211 INLINE void TexturePool::
00212 release_texture(Texture *texture) {
00213   get_global_ptr()->ns_release_texture(texture);
00214 }
00215 
00216 ////////////////////////////////////////////////////////////////////
00217 //     Function: TexturePool::release_all_textures
00218 //       Access: Published, Static
00219 //  Description: Releases all textures in the pool and restores the
00220 //               pool to the empty state.
00221 ////////////////////////////////////////////////////////////////////
00222 INLINE void TexturePool::
00223 release_all_textures() {
00224   get_global_ptr()->ns_release_all_textures();
00225 }
00226 
00227 ////////////////////////////////////////////////////////////////////
00228 //     Function: TexturePool::rehash
00229 //       Access: Published, Static
00230 //  Description: Should be called when the model-path changes, to blow
00231 //               away the cache of texture pathnames found along the
00232 //               model-path.
00233 ////////////////////////////////////////////////////////////////////
00234 INLINE void TexturePool::
00235 rehash() {
00236   get_global_ptr()->_relpath_lookup.clear();
00237 }
00238 
00239 ////////////////////////////////////////////////////////////////////
00240 //     Function: TexturePool::garbage_collect
00241 //       Access: Published, Static
00242 //  Description: Releases only those textures in the pool that have a
00243 //               reference count of exactly 1; i.e. only those
00244 //               textures that are not being used outside of the pool.
00245 //               Returns the number of textures released.
00246 ////////////////////////////////////////////////////////////////////
00247 INLINE int TexturePool::
00248 garbage_collect() {
00249   return get_global_ptr()->ns_garbage_collect();
00250 }
00251 
00252 ////////////////////////////////////////////////////////////////////
00253 //     Function: TexturePool::list_contents
00254 //       Access: Published, Static
00255 //  Description: Lists the contents of the texture pool to the
00256 //               indicated output stream.
00257 ////////////////////////////////////////////////////////////////////
00258 INLINE void TexturePool::
00259 list_contents(ostream &out) {
00260   get_global_ptr()->ns_list_contents(out);
00261 }
00262 
00263 ////////////////////////////////////////////////////////////////////
00264 //     Function: TexturePool::list_contents
00265 //       Access: Published, Static
00266 //  Description: Lists the contents of the texture pool to cout
00267 ////////////////////////////////////////////////////////////////////
00268 INLINE void TexturePool::
00269 list_contents() {
00270   get_global_ptr()->ns_list_contents(cout);
00271 }
00272 
00273 ////////////////////////////////////////////////////////////////////
00274 //     Function: TexturePool::find_texture
00275 //       Access: Published, Static
00276 //  Description: Returns the first texture found in the pool that
00277 //               matches the indicated name (which may contain
00278 //               wildcards).  Returns the texture if it is found, or
00279 //               NULL if it is not.
00280 ////////////////////////////////////////////////////////////////////
00281 INLINE Texture *TexturePool::
00282 find_texture(const string &name) {
00283   return get_global_ptr()->ns_find_texture(name);
00284 }
00285 
00286 ////////////////////////////////////////////////////////////////////
00287 //     Function: TexturePool::find_all_textures
00288 //       Access: Published, Static
00289 //  Description: Returns the set of all textures found in the pool
00290 //               that match the indicated name (which may contain
00291 //               wildcards).
00292 ////////////////////////////////////////////////////////////////////
00293 INLINE TextureCollection TexturePool::
00294 find_all_textures(const string &name) {
00295   return get_global_ptr()->ns_find_all_textures(name);
00296 }
00297 
00298 ////////////////////////////////////////////////////////////////////
00299 //     Function: TexturePool::set_fake_texture_image
00300 //       Access: Published, Static
00301 //  Description: Sets a bogus filename that will be loaded in lieu of
00302 //               any textures requested from this point on.
00303 ////////////////////////////////////////////////////////////////////
00304 INLINE void TexturePool::
00305 set_fake_texture_image(const Filename &filename) {
00306   get_global_ptr()->_fake_texture_image = filename;
00307 }
00308 
00309 ////////////////////////////////////////////////////////////////////
00310 //     Function: TexturePool::clear_fake_texture_image
00311 //       Access: Published, Static
00312 //  Description: Restores normal behavior of loading the textures
00313 //               actually requested.
00314 ////////////////////////////////////////////////////////////////////
00315 INLINE void TexturePool::
00316 clear_fake_texture_image() {
00317   set_fake_texture_image(string());
00318 }
00319 
00320 ////////////////////////////////////////////////////////////////////
00321 //     Function: TexturePool::has_fake_texture_image
00322 //       Access: Published, Static
00323 //  Description: Returns true if fake_texture_image mode has been
00324 //               enabled, false if we are in the normal mode.
00325 ////////////////////////////////////////////////////////////////////
00326 INLINE bool TexturePool::
00327 has_fake_texture_image() {
00328   return !get_fake_texture_image().empty();
00329 }
00330 
00331 ////////////////////////////////////////////////////////////////////
00332 //     Function: TexturePool::get_fake_texture_image
00333 //       Access: Published, Static
00334 //  Description: Returns the filename that was specified with a
00335 //               previous call to set_fake_texture_image().
00336 ////////////////////////////////////////////////////////////////////
00337 INLINE const Filename &TexturePool::
00338 get_fake_texture_image() {
00339   return get_global_ptr()->_fake_texture_image;
00340 }
00341 
00342 ////////////////////////////////////////////////////////////////////
00343 //     Function: TexturePool::make_texture
00344 //       Access: Published, Static
00345 //  Description: Creates a new Texture object of the appropriate type
00346 //               for the indicated filename extension, according to
00347 //               the types that have been registered via
00348 //               register_texture_type().
00349 ////////////////////////////////////////////////////////////////////
00350 PT(Texture) TexturePool::
00351 make_texture(const string &extension) {
00352   return get_global_ptr()->ns_make_texture(extension);
00353 }
 All Classes Functions Variables Enumerations