diguyGraphicsTexture.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2024 MAK Technologies, Inc.
 * All rights reserved.
 ****************************************************************************/

/*********************************************************************/
#ifndef __diguyGraphicsTexture_H
#define __diguyGraphicsTexture_H

#ifdef SWIG
%module diguyGraphicsTexture
#else
#define CPLUSPLUS_ONLY
#endif

#ifdef CPLUSPLUS_ONLY
#include <declspec_diguy.h>
#include <diguy_constants.h>

class bdiGeometryTextureFile;
class diguyGraphicsTexture;


#endif

/****************************************************************************/
/*l
 *b  Description:
 **
 **    This enumeration lists the types of compression that texture map data
 **    may have.
 **
 */
enum diguyGraphicsTextureCompressionType
{
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_NONE = 0,
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_DXT1,
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_DXT2,
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_DXT3,
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_DXT4,
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_DXT5,
   DIGUY_GRAPHICS_TEXTURE_COMPRESSION_TYPE_DXT5_NM
};


/****************************************************************************/
/*l
 *b  Description:
 **
 **    This enumeration lists the type of texture map a given image file is
 **    being used as.
 **
 */
enum diguyTextureMapType
{
   DIGUY_TEXTURE_MAP_TYPE_UNKNOWN = -1,
   DIGUY_TEXTURE_MAP_TYPE_DIFFUSE = 0,
   DIGUY_TEXTURE_MAP_TYPE_SHADOW,
   DIGUY_TEXTURE_MAP_TYPE_SPECULAR,
   DIGUY_TEXTURE_MAP_TYPE_BUMP,
   DIGUY_TEXTURE_MAP_TYPE_COMPONENTS,
   DIGUY_TEXTURE_MAP_TYPE_COMPONENT_RAMP,
   DIGUY_TEXTURE_MAP_TYPE_MISC_1,
   DIGUY_TEXTURE_MAP_TYPE_MISC_2,
   DIGUY_TEXTURE_MAP_TYPE_ANIMATION,
   DIGUY_TEXTURE_MAP_TYPE_DECAL,
   DIGUY_TEXTURE_MAP_TYPE_DECAL_SPECULAR,
   DIGUY_TEXTURE_MAP_TYPE_DECAL_BUMP,
   DIGUY_TEXTURE_MAP_TYPE_COUNT
} ;


/****************************************************************************/
/*l
 *b  Description:
 **
 **    This enumeration lists how the state stores the available textures in
 **    the textures_available bitfield.  Also used by the shader programs.
 **
 */
enum diguyTextureMapMasks
{
   DIGUY_TEXTURE_MAP_MASK_DIFFUSE    = 0x00000001,
   DIGUY_TEXTURE_MAP_MASK_SHADOW     = 0x00000002,
   DIGUY_TEXTURE_MAP_MASK_SPECULAR   = 0x00000004,
   DIGUY_TEXTURE_MAP_MASK_BUMP       = 0x00000008,
   DIGUY_TEXTURE_MAP_MASK_COMPONENTS = 0x00000010,
   DIGUY_TEXTURE_MAP_MASK_MISC_1     = 0x00000020,
   DIGUY_TEXTURE_MAP_MASK_MISC_2     = 0x00000040,
   DIGUY_TEXTURES_MAP_MASK_ALL       = 0xffffffff
} ;

/*l
 *b  Description:
 **
 **    This function converts the passed texture type enumeration into
 **    a NULL-terminated C-style string.
 **
 *b  Returns:
 **
 **    C-style string identifying texture map type
 */

BDI_DECLSPEC_bdiutil const char* diguy_texture_type_to_string(diguyTextureMapType texture_type);

/*l
 *b  Description:
 **
 **    This function converts the passed C-style string into an
 **    enumerated value.
 **
 *b  Returns:
 **
 **    enumeration value of string
 */

BDI_DECLSPEC_bdiutil diguyTextureMapType diguy_texture_type_from_string(const char* string);

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyGraphicsTexture
{

public:

/*****************************************************************************/
   /*l
    *b  Description:
    **
    **    Returns the name of the texture.  This pointer will
    **    never be NULL.
    **
    *b  Returns:
    **
    **    name of the texture
    */
   const char* get_name();

   /*l
    *b  Description:
    **
    **    This function returns the filename of the texture.  This pointer
    **    may be NULL if the texture does not have an associated filename.
    **
    *b  Returns:
    **
    **    filename of the texture
    */
   const char* get_filename();

   const char* get_full_filename();

   const char* get_cached_dds_filename();

   /*l
    *b  Returns:
    **
    **    the width of the texture, in pixels; -1 on failure
    */
   int get_width();

   /*l
    *b  Returns:
    **
    **    the height of the texture, in pixels; -1 on failure
    */
   int get_height();

   /*l
    *b  Description:
    **
    **    This function returns how many components the texture has.  The
    **    number of components will be an integer between 1 and 4.
    **
    **    Most textures have three components, red (R), green (G), and
    **    blue (B), or RGB.  These textures commonly have filenames with
    **    the extension .rgb.
    **
    **    Four component textures add an alpha (A) channel, resulting in
    **    RGBA.  These textures commonly have filenames with the extension
    **    .rgba.
    **
    **    One component textures have only an intensity (I).  These textures
    **    commonly have filenames with the extension .int.
    **
    **    Two component textures have only an intensity (I), and an alpha
    **    channel.  These textures commonly have filenames with the
    **    extension .inta.
    **
    *b  Returns:
    **
    **    number of components in texture; -1 on failure
    */
   int get_num_components();

   /*l
    *b  Description:
    **
    **    This function returns whether the texture contains an alpha
    **    component.  Textures that have an alpha component can make
    **    objects semi-transparent, which can affect when said objects
    **    should be drawn.
    **
    *b  Returns:
    **
    **    1 if texture contains an alpha component, 0 if not; -1 on failure
    */
   int get_contains_alpha_component();

   int get_is_clip_map();

#ifdef CPLUSPLUS_ONLY

   /*l
    *b  Description:
    **
    **    This function returns a memory buffer with the actual texture
    **    data.
    **
    **    The size of buffer can be obtained by calling
    **    get_texture_map_data_size().
    **
    **    The texture information is packed into the buffer row by row,
    **    in the following order:
    **
    *-      - I    (intensity) for one component textures
    *-      - IA   (intensity and alpha) for two component textures
    *-      - RGB  (red, blue, green) for three component textures
    *-      - RGBA (red, blue, green, alpha) for four component textures
    **
    **    There is one byte per component.
    **
    **    This function should not be called after free_loader_memory()
    **    has been called.
    **
    **    Note that some renderers expect to take ownership of the texture
    **    data that is passed to them.  In this case, a copy of this texture
    **    data must be made to avoid a double deletion of the memory.  This
    **    texture data will be deleted by the call to free_loader_memory(),
    **    or when this object is deleted.
    **
    *b  Returns:
    **
    **    pointer to texture map data
    **
    **    NOTE: The returned pointer may be NULL, if there was some problem
    **    loading the texture file.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   unsigned char* get_texture_map_data();

#endif

   /*l
    *b  Description:
    **
    **    This function returns how many bytes are used by the texture
    **    map data buffer.
    **
    *b  Returns:
    **
    **    buffer size of texture map data, in bytes; may be 0 in the
    **    case of a NULL texture
    */
   int get_texture_map_data_size();

   /*l
    *b  Description:
    **
    **    This function returns which compression method, if any, is
    **    applied to the data returned bu get_texture_map_data().
    **
    **    Most often compressed textures come from .dds (DirectDraw Surface)
    **    files.
    **
    *b  Returns:
    **
    **    compression type enumeration
    */
   diguyGraphicsTextureCompressionType get_texture_compression_type();

   /*l
    *b  Description:
    **
    **    This function returns how many mipmaps are already included in
    **    the texture map data.
    **
    **    Typically only .dds (DirectDraw Surface) textures have precomputed
    **    mipmaps in them.
    **
    **    Note that values 0 and 1 are somewhat the same: there is only
    **    one image in the texture map data: the base, unscaled image.
    **
    *b  Returns:
    **
    **    num of included mipmaps
    */
   int get_num_included_mipmaps();

   /*l
    *b  Description:
    **
    **    This function returns the size of the data, in bytes, of the
    **    specified mipmap.
    **
    **    "mipmap" 0 is the base, unscaled image, mipmap 1 is the first
    **    scaled image, etc.
    **
    *b  Returns:
    **
    **    data size, in bytes, of mipmap; -1 on error
    */
   int get_mipmap_data_size(int mipmap);

   /*l
    *b  Description:
    **
    **    This function returns the data offset of the specified mipmap
    **    into the data pointer returned by get_texture_map_data().
    **
    **    "mipmap" 0 is the base, unscaled image, mipmap 1 is the first
    **    scaled image, etc.
    **
    *b  Returns:
    **
    **    data offset, in bytes, of mipmap; -1 on error
    */
   int get_mipmap_data_offset(int mipmap);

   /*l
    *b  Description:
    **
    **    This function returns the OpenGL pixel format enumeration of this
    **    texture.
    **
    **    This enumeration will be one of the following:
    **
    *-    - GL_LUMINANCE
    *-    - GL_LUMINANCE_ALPHA
    *-    - GL_RGB
    *-    - GL_RGBA
    *-    - GL_COMPRESSED_RGB_S3TC_DXT1_EXT
    *-    - GL_COMPRESSED_RGBA_S3TC_DXT1_EXT
    *-    - GL_COMPRESSED_RGBA_S3TC_DXT5_EXT
   .*     - GL_COMPRESSED_RGB_ALPHA_S3TC_DXT1_EXT
   .*     - GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT
    **
    *b  Returns:
    **
    **    OpenGL pixel format enum; -1 on error
    **
    **    In OpenGL and OSG environments, the returned value should be cast
    **    into a GLenum.
    */
   int get_gl_format();

   /*l
    *b  Description:
    **
    **    This function returns the OpenGL pixel format string of this
    **    texture.  There are a large number of potential results depending
    **    if compressed textures and/or sRGB textures are enabled.
    **
    **    Example of possible results:
    **
    *-    - GL_RGB GL_RGBA
    *-    - sRGB: GL_SRGB GL_SRGB_ALPHA
    *-    - Compressed: GL_COMPRESSED_RGB_S3TC_DXT1 GL_COMPRESSED_RGBA_S3TC_DXT5
    *-    - sRGB + Compressed: GL_COMPRESSED_RGB_ALPHA_S3TC_DXT1 GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5
    */
   const char* get_gl_format_as_string();

   int get_is_srgb_texture();

   /*l
    *b  Description:
    **
    **    This function returns the "block size" of the dds compression
    **    types.  This value can be useful in generating mipmap data offsets.
    **
    **    Alternatively, the function get_mipmap_data_offset() can be called
    **    to get the precomputed mipmap data offsets.
    **
    **    Currently this value will be either 8 (for DXT1 compression) or 16
    **    (for DXT3 and DXT5 compression).
    **
    *b  Returns:
    **
    **    block size, in bytes
    */
   int get_dds_block_size();

   /*l
    *b  Description:
    **
    **    For texture indices less than zero and greater than one, a decision
    **    must be made as to whether the texture is repeated or whether the
    **    edge pixels are replicated to fill the space.
    **
    **    This function returns whether the texture should be repeated
    **    horizontally (don't clamp) or whether the edge column of pixels
    **    should be used (do clamp).
    **
    **    Note that in MultiGen Creator attribute (.attr) files, this
    **    corresponds to the "Wrap Method u" attribute.
    **
    *b  Returns:
    **
    **    0 is texture should be tiled, 1 if not; -1 on failure
    */
   int get_clamp_s();

   /*l
    *b  Description:
    **
    **    For texture indices less than zero and greater than one, a
    **    decision must be made as to whether the texture is repeated
    **    or whether the edge pixels are replicated to fill the space.
    **
    **    This function returns whether the texture should be repeated
    **    vertically (don't clamp) or whether the edge row of pixels
    **    should be used (do clamp).
    **
    **    Note that in MultiGen Creator attribute (.attr) files, this
    **    corresponds to the "Wrap Method v" attribute.
    **
    *b  Returns:
    **
    **    0 is texture should be repeated, 1 if not; -1 on failure
    */
   int get_clamp_t();

   int get_is_in_async_load_queue();

   void get_approximate_color(float *r, float *g, float *b);

   /*l
    *b  Description:
    **
    **    This function frees most memory allocated by the DI-Guy geometry
    **    loader for this object.
    **
    **    This function should only be called during or after the object's
    **    build() function has been called.  After it has been called, calls
    **    to many accessor functions will fail.
    */
   void free_loader_memory();


/*****************************************************************************/
#ifdef CPLUSPLUS_ONLY

   /*l
   *b  Description:
   **
   **    This function will be called by DI-Guy after the texture is loaded but before build.
   **    When asynchronous texture loading is active this provides an opportunity to copy data from
   **    DI-Guy structures to end user structures in the background loading thread.
   **
   *i  Immediate Mode:
   **
   **    Immediate mode renderers may override this function.
   **
   *i  Scene Graph:
   **
   **    Scene graph renderers may override this function, if they are using the async texture loader.
   **    may need to be coupled with calls to diguyScenario::run_background_load_update()
   **
   *b  Callable From:
   **
   *-    - N/A (automatically called by DI-Guy Graphics API during
   *-      the Build Stage)
   */
   virtual void asynchronous_post_load();

   /*l
    *b  Description:
    **
    **    This function will be called by DI-Guy when it is time for a
    **    renderer-specific texture object to be created.  At that point
    **    the texture information has been read from the texture file,
    **    and is available via the Accessor Functions above.
    **
    *i  Immediate Mode:
    **
    **    Immediate mode renderers may override this function, to
    **    create an object that may be invoked by bind_now().
    **
    *i  Scene Graph:
    **
    **    Scene graph renderers usually do override this function, to
    **    create an object that gets associated with diguyGraphicsMesh
    **    objects.
    **
    *b  Callable From:
    **
    *-    - N/A (automatically called by DI-Guy Graphics API during
    *-      the Build Stage)
    */
   virtual void build();

   /*l
    *b  Description:
    **
    **    This function will be called by DI-Guy when it is time for a
    **    renderer-specific texture object to be destroyed.
    **
    *i  Immediate Mode:
    **
    **    Immediate mode renderers may override this function, to
    **    destroy any object that may have been created by build().
    **
    *i  Scene Graph:
    **
    **    Scene graph renderers usually do override this function, to
    **    destroy any object that may have been created by build().
    **
    *b  Callable From:
    **
    *-    - N/A (automatically called by DI-Guy Graphics API during
    *-      the Unbuild Stage)
    */
   virtual void unbuild();

   /*l
    *b  Description:
    **
    **    This function will be called by DI-Guy when the texture should
    **    be made active, or bound.
    **
    *i  Immediate Mode:
    **
    **    Immediate mode renderers usually do override this function, to
    **    invoke the object created by build(), or make calls to the
    **    renderer to set appropriate texture state.
    **
    *i  Scene Graph:
    **
    **    Scene graph renderers usually do not override this function.
    **
    *b  Callable From:
    **
    *-    - N/A (automatically called by DI-Guy Graphics API during
    *-      Draw Stage)
    */
   virtual void bind_now(diguyTextureMapType texture_type);

   /*l
    *b  Description:
    **  helper function to let diguy internals know what the object's texture ID is. not normally needed.
    **  (Used by character viewer in gapi mode.)
    **/
   virtual unsigned int get_gl_texture_id() const;

   /*l
    *b  Description:
    **
    **    This function returns the last bound texture used by DI-Guy.  This
    **    value can be used in diguyGraphicsTexture::bind() to check to see
    **    if a texture rebind is necessary; avoiding a texture rebind can
    **    avoid a significant performance hit in some rendering systems.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   static diguyGraphicsTexture* get_last_bound_texture(int texture_unit = 0);

   /*l
    *b  Description:
    **
    **    This function clears out the last bound texture variable.
    **    diguyScenario::draw() automatically calls it, but it is also
    **    recommended that it be called before drawing individual
    **    diguyCharacters in case something outside of DI-Guy has changed
    **    the texture.
    **
    *b  Callable From:
    **
    *-    - C++
    */
   static void clear_last_bound_texture();


#endif

   void load_texture_data(int async_load);

/****************************************************************************/
/****************************************************************************/

#ifdef CPLUSPLUS_ONLY

   bdiGeometryTextureFile* get_scripted_object() {return m_scripted_object;}

protected:

   /*l
    **    A protected constructor.  Constructors are called automatically
    **    by DI-Guy.
    */
   diguyGraphicsTexture(void* internal_data);

   /*l
    **    A protected destructor.  Destructors are called automatically
    **    by DI-Guy.
    */
   virtual ~diguyGraphicsTexture();

private:

   /*l
    **    A pointer to internal data.
    */
   bdiGeometryTextureFile* m_scripted_object;

   friend class bdiGeometryTextureFile;
   friend class bdiGeometryFactory;

#endif

};


#endif /* __diguyGraphicsTexture_H */