Panda3D

texture.h

00001 // Filename: texture.h
00002 // Created by:  mike (09Jan97)
00003 //
00004 ////////////////////////////////////////////////////////////////////
00005 //
00006 // PANDA 3D SOFTWARE
00007 // Copyright (c) Carnegie Mellon University.  All rights reserved.
00008 //
00009 // All use of this software is subject to the terms of the revised BSD
00010 // license.  You should have received a copy of this license along
00011 // with this source code in a file named "LICENSE."
00012 //
00013 ////////////////////////////////////////////////////////////////////
00014 
00015 #ifndef TEXTURE_H
00016 #define TEXTURE_H
00017 
00018 #include "pandabase.h"
00019 
00020 #include "filename.h"
00021 #include "typedWritableReferenceCount.h"
00022 #include "namable.h"
00023 #include "internalName.h"
00024 #include "graphicsStateGuardianBase.h"
00025 #include "updateSeq.h"
00026 #include "pmap.h"
00027 #include "config_gobj.h"
00028 #include "pStatCollector.h"
00029 #include "pmutex.h"
00030 #include "mutexHolder.h"
00031 #include "conditionVarFull.h"
00032 #include "loaderOptions.h"
00033 #include "string_utils.h"
00034 
00035 class PNMImage;
00036 class TextureContext;
00037 class FactoryParams;
00038 class PreparedGraphicsObjects;
00039 class CullTraverser;
00040 class CullTraverserData;
00041 class BamCacheRecord;
00042 class TexturePeeker;
00043 struct DDSHeader;
00044 
00045 ////////////////////////////////////////////////////////////////////
00046 //       Class : Texture
00047 // Description : Represents a texture object, which is typically a
00048 //               single 2-d image but may also represent a 1-d or 3-d
00049 //               texture image, or the six 2-d faces of a cube map
00050 //               texture.
00051 //
00052 //               A texture's image data might be stored in system RAM
00053 //               (see get_ram_image()) or its image may be represented
00054 //               in texture memory on one or more
00055 //               GraphicsStateGuardians (see prepare()), or both.  The
00056 //               typical usage pattern is that a texture is loaded
00057 //               from an image file on disk, which copies its image
00058 //               data into system RAM; then the first time the texture
00059 //               is rendered its image data is copied to texture
00060 //               memory (actually, to the graphics API), and the
00061 //               system RAM image is automatically freed.
00062 ////////////////////////////////////////////////////////////////////
00063 class EXPCL_PANDA_GOBJ Texture : public TypedWritableReferenceCount, public Namable {
00064 PUBLISHED:
00065   enum TextureType {
00066     TT_1d_texture,
00067     TT_2d_texture,
00068     TT_3d_texture,
00069     TT_cube_map,
00070   };
00071 
00072   enum ComponentType {
00073     T_unsigned_byte,
00074     T_unsigned_short,
00075     T_float,
00076     T_unsigned_int_24_8,
00077   };
00078 
00079   enum Format {
00080     F_depth_stencil = 1,
00081     F_color_index,
00082     F_red,
00083     F_green,
00084     F_blue,
00085     F_alpha,
00086     F_rgb,     // any suitable RGB mode, whatever the hardware prefers
00087 
00088     // The following request a particular number of bits for the GSG's
00089     // internal_format (as stored in the framebuffer), but this
00090     // request is not related to the pixel storage within the Texture
00091     // object itself, which is always get_num_components() *
00092     // get_component_width().
00093     F_rgb5,    // 5 bits per R,G,B channel
00094     F_rgb8,    // 8 bits per R,G,B channel
00095     F_rgb12,   // 12 bits per R,G,B channel
00096     F_rgb332,  // 3 bits per R & G, 2 bits for B
00097 
00098     F_rgba,    // any suitable RGBA mode, whatever the hardware prefers
00099 
00100     // Again, the following bitdepth requests are only for the GSG;
00101     // within the Texture object itself, these are all equivalent.
00102     F_rgbm,    // as above, but only requires 1 bit for alpha (i.e. mask)
00103     F_rgba4,   // 4 bits per R,G,B,A channel
00104     F_rgba5,   // 5 bits per R,G,B channel, 1 bit alpha
00105     F_rgba8,   // 8 bits per R,G,B,A channel
00106     F_rgba12,  // 12 bits per R,G,B,A channel
00107 
00108     F_luminance,
00109     F_luminance_alpha,      // 8 bits luminance, 8 bits alpha
00110     F_luminance_alphamask,  // 8 bits luminance, only needs 1 bit of alpha
00111 
00112     F_rgba16,  // 16 bits per R,G,B,A channel
00113     F_rgba32,  // 32 bits per R,G,B,A channel
00114 
00115     F_depth_component,
00116     F_depth_component16,
00117     F_depth_component24,
00118     F_depth_component32,
00119   };
00120 
00121   enum FilterType {
00122     // Mag Filter and Min Filter
00123 
00124     // Point sample the pixel
00125     FT_nearest,
00126 
00127     // Bilinear filtering of four neighboring pixels
00128     FT_linear,
00129 
00130     // Min Filter Only
00131 
00132     // Point sample the pixel from the nearest mipmap level
00133     FT_nearest_mipmap_nearest,
00134 
00135     // Bilinear filter the pixel from the nearest mipmap level
00136     FT_linear_mipmap_nearest,
00137 
00138     // Point sample the pixel from two mipmap levels, and linearly blend
00139     FT_nearest_mipmap_linear,
00140 
00141     // A.k.a. trilinear filtering: Bilinear filter the pixel from
00142     // two mipmap levels, and linearly blend the results.
00143     FT_linear_mipmap_linear,
00144 
00145     // The OpenGL ARB_shadow extension can be thought of as a kind of filtering.
00146     FT_shadow,
00147     
00148     // Default is usually linear, but it depends on format.
00149     // This was added at the end of the list to avoid bumping TXO version #.
00150     FT_default,
00151 
00152     // Returned by string_filter_type() for an invalid match.
00153     FT_invalid
00154   };
00155 
00156   enum WrapMode {
00157     WM_clamp,  // coords that would be outside [0-1] are clamped to 0 or 1
00158     WM_repeat,
00159     WM_mirror,
00160     WM_mirror_once,   // mirror once, then clamp
00161     WM_border_color,  // coords outside [0-1] use explict border color
00162     // Returned by string_wrap_mode() for an invalid match.
00163     WM_invalid
00164   };
00165 
00166   enum CompressionMode {
00167     // Generic compression modes.  Usually, you should choose one of
00168     // these.
00169     CM_default,  // on or off, according to compressed-textures
00170     CM_off,      // uncompressed image
00171     CM_on,       // whatever compression the driver supports
00172 
00173     // Specific compression modes.  Use only when you really want to
00174     // use a particular compression algorithm.  Use with caution; not
00175     // all drivers support all compression modes.  You can use
00176     // GSG::get_supports_compressed_texture_format() to query the
00177     // available compression modes for a particular GSG.
00178     CM_fxt1,
00179     CM_dxt1,
00180     CM_dxt2,
00181     CM_dxt3,
00182     CM_dxt4,
00183     CM_dxt5,
00184   };
00185 
00186   enum QualityLevel {
00187     QL_default,   // according to texture-quality-level
00188     QL_fastest,
00189     QL_normal,
00190     QL_best,
00191   };
00192 
00193 PUBLISHED:
00194   Texture(const string &name = string());
00195 protected:
00196   Texture(const Texture &copy);
00197   void operator = (const Texture &copy);
00198 PUBLISHED:
00199   virtual ~Texture();
00200 
00201   INLINE PT(Texture) make_copy();
00202   INLINE void clear();
00203 
00204   INLINE void setup_texture(TextureType texture_type,
00205                             int x_size, int y_size, int z_size,
00206                             ComponentType component_type, Format format);
00207 
00208   INLINE void setup_1d_texture();
00209   INLINE void setup_1d_texture(int x_size,
00210                                ComponentType component_type, Format format);
00211   INLINE void setup_2d_texture();
00212   INLINE void setup_2d_texture(int x_size, int y_size,
00213                                ComponentType component_type, Format format);
00214   INLINE void setup_3d_texture(int z_size = 1);
00215   INLINE void setup_3d_texture(int x_size, int y_size, int z_size,
00216                                ComponentType component_type, Format format);
00217   INLINE void setup_cube_map();
00218   INLINE void setup_cube_map(int size,
00219                              ComponentType component_type, Format format);
00220 
00221   void generate_normalization_cube_map(int size);
00222   void generate_alpha_scale_map();
00223 
00224   bool read(const Filename &fullpath, const LoaderOptions &options = LoaderOptions());
00225   bool read(const Filename &fullpath, const Filename &alpha_fullpath,
00226             int primary_file_num_channels, int alpha_file_channel,
00227             const LoaderOptions &options = LoaderOptions());
00228   bool read(const Filename &fullpath, int z, int n, 
00229             bool read_pages, bool read_mipmaps,
00230             const LoaderOptions &options = LoaderOptions());
00231   bool read(const Filename &fullpath, const Filename &alpha_fullpath,
00232             int primary_file_num_channels, int alpha_file_channel,
00233             int z, int n, bool read_pages, bool read_mipmaps,
00234             BamCacheRecord *record = NULL,
00235             const LoaderOptions &options = LoaderOptions());
00236 
00237   INLINE bool write(const Filename &fullpath);
00238   INLINE bool write(const Filename &fullpath, int z, int n, 
00239                     bool write_pages, bool write_mipmaps);
00240 
00241   bool read_txo(istream &in, const string &filename = "stream");
00242   bool write_txo(ostream &out, const string &filename = "stream") const;
00243   bool read_dds(istream &in, const string &filename = "stream", bool header_only = false);
00244 
00245   INLINE bool load(const PNMImage &pnmimage, const LoaderOptions &options = LoaderOptions());
00246   INLINE bool load(const PNMImage &pnmimage, int z, int n, const LoaderOptions &options = LoaderOptions());
00247   INLINE bool store(PNMImage &pnmimage) const;
00248   INLINE bool store(PNMImage &pnmimage, int z, int n) const;
00249 
00250   INLINE bool reload();
00251   Texture *load_related(const InternalName *suffix) const;
00252 
00253   INLINE bool has_filename() const;
00254   INLINE const Filename &get_filename() const;
00255   INLINE bool has_alpha_filename() const;
00256   INLINE const Filename &get_alpha_filename() const;
00257 
00258   INLINE bool has_fullpath() const;
00259   INLINE const Filename &get_fullpath() const;
00260   INLINE bool has_alpha_fullpath() const;
00261   INLINE const Filename &get_alpha_fullpath() const;
00262 
00263   INLINE int get_x_size() const;
00264   INLINE int get_y_size() const;
00265   INLINE int get_z_size() const;
00266   INLINE int get_num_components() const;
00267   INLINE int get_component_width() const;
00268   INLINE TextureType get_texture_type() const;
00269   INLINE Format get_format() const;
00270   INLINE ComponentType get_component_type() const;
00271 
00272   INLINE void set_wrap_u(WrapMode wrap);
00273   INLINE void set_wrap_v(WrapMode wrap);
00274   INLINE void set_wrap_w(WrapMode wrap);
00275   INLINE void set_minfilter(FilterType filter);
00276   INLINE void set_magfilter(FilterType filter);
00277   INLINE void set_anisotropic_degree(int anisotropic_degree);
00278   INLINE void set_border_color(const Colorf &color);
00279   INLINE void set_compression(CompressionMode compression);
00280   INLINE void set_render_to_texture(bool render_to_texture);
00281 
00282   INLINE WrapMode get_wrap_u() const;
00283   INLINE WrapMode get_wrap_v() const;
00284   INLINE WrapMode get_wrap_w() const;
00285   INLINE FilterType get_minfilter() const;
00286   INLINE FilterType get_magfilter() const;
00287   FilterType get_effective_minfilter() const;
00288   FilterType get_effective_magfilter() const;
00289   INLINE int get_anisotropic_degree() const;
00290   INLINE int get_effective_anisotropic_degree() const;
00291   INLINE Colorf get_border_color() const;
00292   INLINE CompressionMode get_compression() const;
00293   INLINE bool has_compression() const;
00294   INLINE bool get_render_to_texture() const;
00295   INLINE bool uses_mipmaps() const;
00296 
00297   INLINE void set_quality_level(QualityLevel quality_level);
00298   INLINE QualityLevel get_quality_level() const;
00299   INLINE QualityLevel get_effective_quality_level() const;
00300 
00301   INLINE int get_expected_num_mipmap_levels() const;
00302   INLINE int get_expected_mipmap_x_size(int n) const;
00303   INLINE int get_expected_mipmap_y_size(int n) const;
00304   INLINE int get_expected_mipmap_z_size(int n) const;
00305 
00306   INLINE bool has_ram_image() const;
00307   INLINE bool has_uncompressed_ram_image() const;
00308   INLINE bool might_have_ram_image() const;
00309   INLINE size_t get_ram_image_size() const;
00310   INLINE size_t get_ram_page_size() const;
00311   INLINE size_t get_expected_ram_image_size() const;
00312   INLINE size_t get_expected_ram_page_size() const;
00313   INLINE CPTA_uchar get_ram_image();
00314   INLINE CompressionMode get_ram_image_compression() const;
00315   INLINE CPTA_uchar get_uncompressed_ram_image();
00316   CPTA_uchar get_ram_image_as(const string &requested_format);
00317   INLINE PTA_uchar modify_ram_image();
00318   INLINE PTA_uchar make_ram_image();
00319   void set_ram_image(CPTA_uchar image, CompressionMode compression = CM_off,
00320                      size_t page_size = 0);
00321   INLINE void clear_ram_image();
00322   INLINE void set_keep_ram_image(bool keep_ram_image);
00323   virtual bool get_keep_ram_image() const;
00324 
00325   INLINE bool compress_ram_image(CompressionMode compression = CM_on,
00326                                  QualityLevel quality_level = QL_default,
00327                                  GraphicsStateGuardianBase *gsg = NULL);
00328   INLINE bool uncompress_ram_image();
00329 
00330   INLINE int get_num_ram_mipmap_images() const;
00331   INLINE bool has_ram_mipmap_image(int n) const;
00332   int get_num_loadable_ram_mipmap_images() const;
00333   INLINE bool has_all_ram_mipmap_images() const;
00334   INLINE size_t get_ram_mipmap_image_size(int n) const;
00335   INLINE size_t get_ram_mipmap_page_size(int n) const;
00336   INLINE size_t get_expected_ram_mipmap_image_size(int n) const;
00337   INLINE size_t get_expected_ram_mipmap_page_size(int n) const;
00338   CPTA_uchar get_ram_mipmap_image(int n);
00339   void *get_ram_mipmap_pointer(int n);
00340   INLINE PTA_uchar modify_ram_mipmap_image(int n);
00341   INLINE PTA_uchar make_ram_mipmap_image(int n);
00342   void set_ram_mipmap_pointer(int n, void *image, size_t page_size = 0);
00343   void set_ram_mipmap_pointer_from_int(long long pointer, int n, int page_size);
00344   INLINE void set_ram_mipmap_image(int n, CPTA_uchar image, size_t page_size = 0);
00345   void clear_ram_mipmap_image(int n);
00346   INLINE void clear_ram_mipmap_images();
00347   INLINE void generate_ram_mipmap_images();
00348 
00349   INLINE int get_simple_x_size() const;
00350   INLINE int get_simple_y_size() const;
00351   INLINE bool has_simple_ram_image() const;
00352   INLINE size_t get_simple_ram_image_size() const;
00353   INLINE CPTA_uchar get_simple_ram_image() const;
00354   INLINE void set_simple_ram_image(CPTA_uchar image, int x_size, int y_size);
00355   PTA_uchar modify_simple_ram_image();
00356   PTA_uchar new_simple_ram_image(int x_size, int y_size);
00357   void generate_simple_ram_image();
00358   INLINE void clear_simple_ram_image();
00359 
00360   PT(TexturePeeker) peek();
00361 
00362   INLINE UpdateSeq get_properties_modified() const;
00363   INLINE UpdateSeq get_image_modified() const;
00364   INLINE UpdateSeq get_simple_image_modified() const;
00365 
00366   void prepare(PreparedGraphicsObjects *prepared_objects);
00367   bool is_prepared(PreparedGraphicsObjects *prepared_objects) const;
00368   bool was_image_modified(PreparedGraphicsObjects *prepared_objects) const;
00369   size_t get_data_size_bytes(PreparedGraphicsObjects *prepared_objects) const;
00370   bool get_active(PreparedGraphicsObjects *prepared_objects) const;
00371   bool get_resident(PreparedGraphicsObjects *prepared_objects) const;
00372 
00373   bool release(PreparedGraphicsObjects *prepared_objects);
00374   int release_all();
00375 
00376   void write(ostream &out, int indent_level) const;
00377 
00378   size_t estimate_texture_memory() const;
00379 
00380   void set_aux_data(const string &key, TypedReferenceCount *aux_data);
00381   void clear_aux_data(const string &key);
00382   TypedReferenceCount *get_aux_data(const string &key) const;
00383 
00384   INLINE static void set_textures_power_2(AutoTextureScale scale);
00385   INLINE static AutoTextureScale get_textures_power_2();
00386   INLINE static bool have_textures_power_2();
00387 
00388 PUBLISHED:
00389   // These are published, but in general, you shouldn't be mucking
00390   // with these values; they are set automatically when a texture is
00391   // loaded.
00392   INLINE void set_filename(const Filename &filename);
00393   INLINE void clear_filename();
00394   INLINE void set_alpha_filename(const Filename &alpha_filename);
00395   INLINE void clear_alpha_filename();
00396 
00397   INLINE void set_fullpath(const Filename &fullpath);
00398   INLINE void clear_fullpath();
00399   INLINE void set_alpha_fullpath(const Filename &alpha_fullpath);
00400   INLINE void clear_alpha_fullpath();
00401 
00402   INLINE void set_x_size(int x_size);
00403   INLINE void set_y_size(int y_size);
00404   INLINE void set_z_size(int z_size);
00405 
00406   INLINE int get_pad_x_size() const;
00407   INLINE int get_pad_y_size() const;
00408   INLINE int get_pad_z_size() const;
00409   
00410   INLINE void set_pad_size(int x=0, int y=0, int z=0);
00411   void set_size_padded(int x=1, int y=1, int z=1);
00412 
00413   INLINE int get_orig_file_x_size() const;
00414   INLINE int get_orig_file_y_size() const;
00415   INLINE int get_orig_file_z_size() const;
00416 
00417   void set_orig_file_size(int x, int y, int z = 1);
00418   
00419   INLINE void set_format(Format format);
00420   INLINE void set_component_type(ComponentType component_type);
00421   INLINE void set_loaded_from_image();
00422   INLINE bool get_loaded_from_image() const;
00423 
00424   INLINE void set_loaded_from_txo();
00425   INLINE bool get_loaded_from_txo() const;
00426 
00427   static bool is_mipmap(FilterType type);
00428 
00429   INLINE bool get_match_framebuffer_format() const;
00430   INLINE void set_match_framebuffer_format(bool flag);
00431 
00432   INLINE bool get_post_load_store_cache() const;
00433   INLINE void set_post_load_store_cache(bool flag);
00434 
00435   TextureContext *prepare_now(PreparedGraphicsObjects *prepared_objects,
00436                               GraphicsStateGuardianBase *gsg);
00437 
00438   static int up_to_power_2(int value);
00439   static int down_to_power_2(int value);
00440 
00441   void consider_rescale(PNMImage &pnmimage);
00442   static void consider_rescale(PNMImage &pnmimage, const string &name);
00443 
00444 public:
00445   void texture_uploaded();
00446   
00447   virtual bool has_cull_callback() const;
00448   virtual bool cull_callback(CullTraverser *trav, const CullTraverserData &data) const;
00449 
00450   static WrapMode string_wrap_mode(const string &string);
00451   static FilterType string_filter_type(const string &string);
00452 
00453   static PT(Texture) make_texture();
00454 
00455 public:
00456   static bool is_specific(CompressionMode compression);
00457   static bool has_alpha(Format format);
00458   static bool has_binary_alpha(Format format);
00459 
00460   static bool adjust_size(int &x_size, int &y_size, const string &name);
00461 
00462 protected:
00463   virtual void reconsider_dirty();
00464 
00465   // All of the functions in this class that begin "do_" are protected
00466   // methods.  Many of them are implementations of public-facing
00467   // versions of the same methods.
00468 
00469   // All of these assume the lock is already held; generally, they
00470   // also avoid adjusting the _properties_modified and _image_modified
00471   // semaphores.
00472 
00473   virtual bool do_read(const Filename &fullpath, const Filename &alpha_fullpath,
00474                        int primary_file_num_channels, int alpha_file_channel,
00475                        int z, int n, bool read_pages, bool read_mipmaps,
00476                        const LoaderOptions &options, BamCacheRecord *record);
00477   virtual bool do_read_one(const Filename &fullpath, const Filename &alpha_fullpath,
00478                            int z, int n, int primary_file_num_channels, int alpha_file_channel,
00479                            const LoaderOptions &options,
00480                            bool header_only, BamCacheRecord *record);
00481   virtual bool do_load_one(const PNMImage &pnmimage, const string &name,
00482                            int z, int n, const LoaderOptions &options);
00483   bool do_read_txo_file(const Filename &fullpath);
00484   bool do_read_txo(istream &in, const string &filename);
00485   bool do_read_dds_file(const Filename &fullpath, bool header_only);
00486   bool do_read_dds(istream &in, const string &filename, bool header_only);
00487 
00488   bool do_write(const Filename &fullpath, int z, int n, 
00489                 bool write_pages, bool write_mipmaps) const;
00490   bool do_write_one(const Filename &fullpath, int z, int n) const;
00491   bool do_store_one(PNMImage &pnmimage, int z, int n) const;
00492   bool do_write_txo_file(const Filename &fullpath) const;
00493   bool do_write_txo(ostream &out, const string &filename) const;
00494 
00495   void do_unlock_and_reload_ram_image(bool allow_compression);
00496   virtual void do_reload_ram_image(bool allow_compression);
00497   PTA_uchar do_modify_ram_image();
00498   PTA_uchar do_make_ram_image();
00499   PTA_uchar do_modify_ram_mipmap_image(int n);
00500   PTA_uchar do_make_ram_mipmap_image(int n);
00501   void do_set_ram_mipmap_image(int n, CPTA_uchar image, size_t page_size);
00502 
00503   bool consider_auto_process_ram_image(bool generate_mipmaps, 
00504                                        bool allow_compression);
00505   bool do_compress_ram_image(CompressionMode compression,
00506                              QualityLevel quality_level,
00507                              GraphicsStateGuardianBase *gsg);
00508   bool do_uncompress_ram_image();
00509   bool do_has_all_ram_mipmap_images() const;
00510 
00511   bool do_reconsider_z_size(int z);
00512   bool do_reconsider_image_properties(int x_size, int y_size, int num_components,
00513                                       ComponentType component_type, int z,
00514                                       const LoaderOptions &options);
00515 
00516   virtual PT(Texture) do_make_copy();
00517   void do_assign(const Texture &copy);
00518   virtual void do_clear();
00519   void do_setup_texture(TextureType texture_type, int x_size, int y_size,
00520                         int z_size, ComponentType component_type,
00521                         Format format);
00522   void do_set_format(Format format);
00523   void do_set_component_type(ComponentType component_type);
00524   void do_set_x_size(int x_size);
00525   void do_set_y_size(int y_size);
00526   void do_set_z_size(int z_size);
00527 
00528   void do_set_wrap_u(WrapMode wrap);
00529   void do_set_wrap_v(WrapMode wrap);
00530   void do_set_wrap_w(WrapMode wrap);
00531   void do_set_minfilter(FilterType filter);
00532   void do_set_magfilter(FilterType filter);
00533   void do_set_anisotropic_degree(int anisotropic_degree);
00534   void do_set_border_color(const Colorf &color);
00535   void do_set_compression(CompressionMode compression);
00536   void do_set_quality_level(QualityLevel quality_level);
00537 
00538   bool do_has_compression() const;
00539   virtual bool do_has_ram_image() const;
00540   virtual bool do_has_uncompressed_ram_image() const;
00541   CPTA_uchar do_get_ram_image();
00542   CPTA_uchar do_get_uncompressed_ram_image();
00543   void do_set_simple_ram_image(CPTA_uchar image, int x_size, int y_size);
00544   INLINE size_t do_get_ram_image_size() const;
00545   INLINE bool do_has_ram_mipmap_image(int n) const;
00546   int do_get_expected_num_mipmap_levels() const;
00547   INLINE size_t do_get_expected_ram_image_size() const;
00548   INLINE size_t do_get_expected_ram_page_size() const;
00549   size_t do_get_ram_mipmap_page_size(int n) const;
00550   INLINE size_t do_get_expected_ram_mipmap_image_size(int n) const;
00551   INLINE size_t do_get_expected_ram_mipmap_page_size(int n) const;
00552   int do_get_expected_mipmap_x_size(int n) const;
00553   int do_get_expected_mipmap_y_size(int n) const;
00554   int do_get_expected_mipmap_z_size(int n) const;
00555   INLINE void do_clear_ram_image();
00556   void do_clear_simple_ram_image();
00557   void do_clear_ram_mipmap_images();
00558   void do_generate_ram_mipmap_images();
00559   void do_set_pad_size(int x, int y, int z);
00560   bool do_reload();
00561 
00562   // This nested class declaration is used below.
00563   class RamImage {
00564   public:
00565     INLINE RamImage();
00566 
00567     PTA_uchar _image;
00568     size_t _page_size;
00569 
00570     // If _pointer_image is non-NULL, it represents an external block
00571     // of memory that is used instead of the above PTA_uchar.
00572     void *_pointer_image;
00573   };
00574 
00575 private:
00576   static void convert_from_pnmimage(PTA_uchar &image, size_t page_size, 
00577                                     int z, const PNMImage &pnmimage,
00578                                     int num_components, int component_width);
00579   static bool convert_to_pnmimage(PNMImage &pnmimage, int x_size, int y_size,
00580                                   int num_components, int component_width,
00581                                   CPTA_uchar image, size_t page_size, 
00582                                   int z);
00583   static PTA_uchar read_dds_level_rgb8(Texture *tex, const DDSHeader &header, 
00584                                        int n, istream &in);
00585   static PTA_uchar read_dds_level_bgr8(Texture *tex, const DDSHeader &header, 
00586                                        int n, istream &in);
00587   static PTA_uchar read_dds_level_abgr8(Texture *tex, const DDSHeader &header, 
00588                                         int n, istream &in);
00589   static PTA_uchar read_dds_level_rgba8(Texture *tex, const DDSHeader &header, 
00590                                         int n, istream &in);
00591   static PTA_uchar read_dds_level_generic_uncompressed(Texture *tex, 
00592                                                        const DDSHeader &header, 
00593                                                        int n, istream &in);
00594   static PTA_uchar read_dds_level_luminance_uncompressed(Texture *tex, 
00595                                                          const DDSHeader &header, 
00596                                                          int n, istream &in);
00597   static PTA_uchar read_dds_level_dxt1(Texture *tex, 
00598                                        const DDSHeader &header, 
00599                                        int n, istream &in);
00600   static PTA_uchar read_dds_level_dxt23(Texture *tex, 
00601                                         const DDSHeader &header, 
00602                                         int n, istream &in);
00603   static PTA_uchar read_dds_level_dxt45(Texture *tex, 
00604                                         const DDSHeader &header, 
00605                                         int n, istream &in);
00606 
00607   void clear_prepared(PreparedGraphicsObjects *prepared_objects);
00608 
00609   static void consider_downgrade(PNMImage &pnmimage, int num_channels, const string &name);
00610 
00611   static bool compare_images(const PNMImage &a, const PNMImage &b);
00612 
00613   INLINE static void store_unscaled_byte(unsigned char *&p, int value);
00614   INLINE static void store_unscaled_short(unsigned char *&p, int value);
00615   INLINE static void store_scaled_byte(unsigned char *&p, int value, double scale);
00616   INLINE static void store_scaled_short(unsigned char *&p, int value, double scale);
00617   INLINE static double get_unsigned_byte(const unsigned char *&p);
00618   INLINE static double get_unsigned_short(const unsigned char *&p);
00619 
00620   INLINE static bool is_txo_filename(const Filename &fullpath);
00621   INLINE static bool is_dds_filename(const Filename &fullpath);
00622 
00623   void filter_2d_mipmap_pages(RamImage &to, const RamImage &from,
00624                               int x_size, int y_size);
00625 
00626   void filter_3d_mipmap_level(RamImage &to, const RamImage &from,
00627                               int x_size, int y_size, int z_size);
00628 
00629   typedef void Filter2DComponent(unsigned char *&p, 
00630                                  const unsigned char *&q,
00631                                  size_t pixel_size, size_t row_size);
00632 
00633   typedef void Filter3DComponent(unsigned char *&p, 
00634                                  const unsigned char *&q,
00635                                  size_t pixel_size, size_t row_size,
00636                                  size_t page_size);
00637 
00638   static void filter_2d_unsigned_byte(unsigned char *&p, 
00639                                       const unsigned char *&q,
00640                                       size_t pixel_size, size_t row_size);
00641   static void filter_2d_unsigned_short(unsigned char *&p, 
00642                                        const unsigned char *&q,
00643                                        size_t pixel_size, size_t row_size);
00644 
00645   static void filter_3d_unsigned_byte(unsigned char *&p, 
00646                                       const unsigned char *&q,
00647                                       size_t pixel_size, size_t row_size,
00648                                       size_t page_size);
00649   static void filter_3d_unsigned_short(unsigned char *&p, 
00650                                        const unsigned char *&q,
00651                                        size_t pixel_size, size_t row_size,
00652                                        size_t page_size);
00653   
00654   bool do_squish(CompressionMode compression, int squish_flags);
00655   bool do_unsquish(int squish_flags);
00656 
00657 protected:
00658   // Protects all of the members of this class.
00659   Mutex _lock;
00660   // Used to implement do_unlock_and_reload_ram_image()
00661   ConditionVarFull _cvar;  // condition: _reloading is true.
00662   bool _reloading;
00663 
00664   Filename _filename;
00665   Filename _alpha_filename;
00666   Filename _fullpath;
00667   Filename _alpha_fullpath;
00668   Filename _texture_pool_key;
00669 
00670   // The number of channels of the primary file we use.  1, 2, 3, or 4.
00671   int _primary_file_num_channels;
00672 
00673   // If we have a separate alpha file, this designates which channel
00674   // in the alpha file provides the alpha channel.  0 indicates the
00675   // combined grayscale value of rgb; otherwise, 1, 2, 3, or 4 are
00676   // valid.
00677   int _alpha_file_channel;
00678 
00679   int _x_size;
00680   int _y_size;
00681   int _z_size;
00682   int _num_components;
00683   int _component_width;
00684   TextureType _texture_type;
00685   Format _format;
00686   ComponentType _component_type;
00687 
00688   bool _loaded_from_image;
00689   bool _loaded_from_txo;
00690   bool _has_read_pages;
00691   bool _has_read_mipmaps;
00692   int _num_mipmap_levels_read;
00693 
00694   WrapMode _wrap_u;
00695   WrapMode _wrap_v;
00696   WrapMode _wrap_w;
00697   FilterType _minfilter;
00698   FilterType _magfilter;
00699   int _anisotropic_degree;
00700   bool _keep_ram_image;
00701   Colorf _border_color;
00702   CompressionMode _compression;
00703   bool _render_to_texture;
00704   bool _match_framebuffer_format;
00705   bool _post_load_store_cache;
00706   QualityLevel _quality_level;
00707 
00708   int _pad_x_size;
00709   int _pad_y_size;
00710   int _pad_z_size;
00711 
00712   int _orig_file_x_size;
00713   int _orig_file_y_size;
00714   
00715   // A Texture keeps a list (actually, a map) of all the
00716   // PreparedGraphicsObjects tables that it has been prepared into.
00717   // Each PGO conversely keeps a list (a set) of all the Textures that
00718   // have been prepared there.  When either destructs, it removes
00719   // itself from the other's list.
00720   typedef pmap<PreparedGraphicsObjects *, TextureContext *> Contexts;
00721   Contexts _contexts;
00722   
00723   // It is common, when using normal maps, specular maps, gloss maps,
00724   // and such, to use a file naming convention where the filenames
00725   // of the special maps are derived by concatenating a suffix to
00726   // the name of the diffuse map.  The following table enables
00727   // lookup of the special maps given the diffuse map and the suffix.
00728   typedef pmap<CPT(InternalName), PT(Texture)> RelatedTextures;
00729   RelatedTextures _related_textures;
00730   
00731   CompressionMode _ram_image_compression;
00732 
00733   // There is usually one RamImage for the mipmap level 0 (the base
00734   // image).  There may or may not also be additional images for the
00735   // additional mipmap levels.
00736   typedef pvector<RamImage> RamImages;
00737   RamImages _ram_images;
00738 
00739   // This is the simple image, which may be loaded before the texture
00740   // is loaded from disk.  It exists only for 2-d textures.
00741   RamImage _simple_ram_image;
00742   int _simple_x_size;
00743   int _simple_y_size;
00744   PN_int32 _simple_image_date_generated;
00745   
00746   UpdateSeq _properties_modified;
00747   UpdateSeq _image_modified;
00748   UpdateSeq _simple_image_modified;
00749   
00750 private:
00751   // The auxiliary data is not recorded to a bam file.
00752   typedef pmap<string, PT(TypedReferenceCount) > AuxData;
00753   AuxData _aux_data;
00754 
00755   static AutoTextureScale _textures_power_2;
00756   static PStatCollector _texture_read_pcollector;
00757 
00758   // Datagram stuff
00759 public:
00760   static void register_with_read_factory();
00761   virtual void write_datagram(BamWriter *manager, Datagram &me);
00762 
00763 protected:
00764   static TypedWritable *make_from_bam(const FactoryParams &params);
00765   void fillin(DatagramIterator &scan, BamReader *manager, bool has_rawdata);
00766   void fillin_from(Texture *dummy);
00767 
00768 public:
00769   static TypeHandle get_class_type() {
00770     return _type_handle;
00771   }
00772   static void init_type() {
00773     TypedWritableReferenceCount::init_type();
00774     register_type(_type_handle, "Texture",
00775                   TypedWritableReferenceCount::get_class_type());
00776   }
00777   virtual TypeHandle get_type() const {
00778     return get_class_type();
00779   }
00780   virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
00781 
00782 private:
00783 
00784   static TypeHandle _type_handle;
00785 
00786   friend class TextureContext;
00787   friend class PreparedGraphicsObjects;
00788   friend class TexturePool;
00789   friend class TexturePeeker;
00790 };
00791 
00792 extern EXPCL_PANDA_GOBJ ConfigVariableEnum<Texture::QualityLevel> texture_quality_level;
00793 extern EXPCL_PANDA_GOBJ ConfigVariableEnum<Texture::FilterType> texture_minfilter;
00794 extern EXPCL_PANDA_GOBJ ConfigVariableEnum<Texture::FilterType> texture_magfilter;
00795 extern EXPCL_PANDA_GOBJ ConfigVariableInt texture_anisotropic_degree;
00796 
00797 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::TextureType tt);
00798 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::ComponentType ct);
00799 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::Format f);
00800 
00801 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::FilterType ft);
00802 EXPCL_PANDA_GOBJ istream &operator >> (istream &in, Texture::FilterType &ft);
00803 
00804 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::WrapMode wm);
00805 EXPCL_PANDA_GOBJ istream &operator >> (istream &in, Texture::WrapMode &wm);
00806 
00807 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::CompressionMode cm);
00808 EXPCL_PANDA_GOBJ ostream &operator << (ostream &out, Texture::QualityLevel tql);
00809 EXPCL_PANDA_GOBJ istream &operator >> (istream &in, Texture::QualityLevel &tql);
00810 
00811 #include "texture.I"
00812 
00813 #endif
00814 
 All Classes Functions Variables Enumerations