diguyGraphicsTexture

Generated from diguyGraphicsTexture.h

DI-Guy API Version 12.5.1

This file was automatically generated from diguyGraphicsTexture.h. Do not edit this file directly; the changes will be lost.

Includes: declspec_diguy.h | diguy_constants.h

Contents:

Alphabetical Index

Link against: libdiguy_graphics_api

enumeration diguyGraphicsTextureCompressionType

typedef enum
{
	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
} diguyGraphicsTextureCompressionType;

Description:

This enumeration lists the types of compression that texture map data may have.

enumeration diguyTextureMapType

typedef enum
{
	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
} diguyTextureMapType;

Description:

This enumeration lists the type of texture map a given image file is being used as.

enumeration diguyTextureMapMasks

typedef enum
{
	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
} diguyTextureMapMasks;

Description:

This enumeration lists how the state stores the available textures in the textures_available bitfield. Also used by the shader programs.

class diguyGraphicsTexture

Description:

This function converts the passed C-style string into an enumerated value.

Returns:

enumeration value of string

Callable From:

C++
Script

class BDI_DECLSPEC_diguy diguyGraphicsTexture
{
public:
    const char* get_name();
    const char* get_filename();
    int get_width();
    int get_height();
    int get_num_components();
    int get_contains_alpha_component();
#ifdef CPLUSPLUS_ONLY
    unsigned char* get_texture_map_data();
#endif
    int get_texture_map_data_size();
    diguyGraphicsTextureCompressionType get_texture_compression_type();
    int get_num_included_mipmaps();
    int get_mipmap_data_size(int mipmap);
    int get_mipmap_data_offset(int mipmap);
    int get_gl_format();
    const char* get_gl_format_as_string();
    int get_dds_block_size();
    int get_clamp_s();
    int get_clamp_t();
    void free_loader_memory();
#ifdef CPLUSPLUS_ONLY
    virtual void build();
    virtual void unbuild();
    virtual void bind_now(diguyTextureMapType texture_type);
    static diguyGraphicsTexture* get_last_bound_texture(int texture_unit = 0);
    static void clear_last_bound_texture();
#endif

Accessor Functions

The functions in this section provide access to data in this object. They are designed to be called by DI-Guy programmers.

function diguyGraphicsTexture::get_name

Prototype:
const char* get_name();
Description:

Returns the name of the texture. This pointer will never be NULL.
Returns:

name of the texture
Callable From:

C++

function diguyGraphicsTexture::get_filename

Prototype:
const char* get_filename();
Description:

This function returns the filename of the texture. This pointer may be NULL if the texture does not have an associated filename.
Returns:

filename of the texture
Callable From:

C++

function diguyGraphicsTexture::get_width

Prototype:
int get_width();
Returns:

the width of the texture, in pixels; -1 on failure
Callable From:

C++

function diguyGraphicsTexture::get_height

Prototype:
int get_height();
Returns:

the height of the texture, in pixels; -1 on failure
Callable From:

C++

function diguyGraphicsTexture::get_num_components

Prototype:
int get_num_components();
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.
Returns:

number of components in texture; -1 on failure
Callable From:

C++

function diguyGraphicsTexture::get_contains_alpha_component

Prototype:
int get_contains_alpha_component();
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.
Returns:

1 if texture contains an alpha component, 0 if not; -1 on failure
Callable From:

C++

function diguyGraphicsTexture::get_texture_map_data_size

Prototype:
int get_texture_map_data_size();
Description:

This function returns how many bytes are used by the texture map data buffer.
Returns:

buffer size of texture map data, in bytes; may be 0 in the case of a NULL texture
Callable From:

C++

function diguyGraphicsTexture::get_texture_compression_type

Prototype:
diguyGraphicsTextureCompressionType get_texture_compression_type();
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.
Returns:

compression type enumeration
Callable From:

C++

function diguyGraphicsTexture::get_num_included_mipmaps

Prototype:
int get_num_included_mipmaps();
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.
Returns:

num of included mipmaps
Callable From:

C++

function diguyGraphicsTexture::get_mipmap_data_size

Prototype:
int get_mipmap_data_size(int mipmap);
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.
Returns:

data size, in bytes, of mipmap; -1 on error
Callable From:

C++

function diguyGraphicsTexture::get_mipmap_data_offset

Prototype:
int get_mipmap_data_offset(int mipmap);
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.
Returns:

data offset, in bytes, of mipmap; -1 on error
Callable From:

C++

function diguyGraphicsTexture::get_gl_format

Prototype:
int get_gl_format();
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
Returns:

OpenGL pixel format enum; -1 on error

In OpenGL and OSG environments, the returned value should be cast into a GLenum.
Callable From:

C++

function diguyGraphicsTexture::get_gl_format_as_string

Prototype:
const char* get_gl_format_as_string();
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

function diguyGraphicsTexture::get_dds_block_size

Prototype:
int get_dds_block_size();
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).
Returns:

block size, in bytes
Callable From:

C++

function diguyGraphicsTexture::get_clamp_s

Prototype:
int get_clamp_s();
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.
Returns:

0 is texture should be tiled, 1 if not; -1 on failure
Callable From:

C++

function diguyGraphicsTexture::get_clamp_t

Prototype:
int get_clamp_t();
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.
Returns:

0 is texture should be repeated, 1 if not; -1 on failure
Callable From:

C++

function diguyGraphicsTexture::free_loader_memory

Prototype:
void free_loader_memory();
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.
Callable From:

C++

Virtual Functions

The functions in this section are all virtual functions that will be called by DI-Guy at various times during DI-Guy execution.

Because the functions are all virtual, DI-Guy programmers can create a subclass of this class and override them. Unless otherwise stated, the base class functions do not need to be called.

function diguyGraphicsTexture::build

Prototype:
virtual void build();
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.
Immediate Mode:

Immediate mode renderers may override this function, to create an object that may be invoked by bind_now().
Scene Graph:

Scene graph renderers usually do override this function, to create an object that gets associated with diguyGraphicsMesh objects.
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage)

function diguyGraphicsTexture::unbuild

Prototype:
virtual void unbuild();
Description:

This function will be called by DI-Guy when it is time for a renderer-specific texture object to be destroyed.
Immediate Mode:

Immediate mode renderers may override this function, to destroy any object that may have been created by build().
Scene Graph:

Scene graph renderers usually do override this function, to destroy any object that may have been created by build().
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Unbuild Stage)

function diguyGraphicsTexture::bind_now

Prototype:
virtual void bind_now(diguyTextureMapType texture_type);
Description:

This function will be called by DI-Guy when the texture should be made active, or bound.
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.
Scene Graph:

Scene graph renderers usually do not override this function.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Draw Stage)

function diguyGraphicsTexture::get_last_bound_texture

Prototype:
static diguyGraphicsTexture* get_last_bound_texture(int texture_unit = 0);
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.
Callable From:

C++

function diguyGraphicsTexture::clear_last_bound_texture

Prototype:
static void clear_last_bound_texture();
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.
Callable From:

C++

Alphabetical Index

These coded instructions, statements, and computer programs contain unpublished proprietary information of Boston Dynamics and are protected by Copyright Laws of the United States. They may not be used, duplicated, or disclosed in any form, in whole or in part, without the prior written consent from Boston Dynamics.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Sofware clause at DFARS 252.227-7013 and/or in similar or successor clauses in the FAR, or the DOD or NASA FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software--Restricted Rights at 48 CFR 52.227-19, as applicable. Unpublished-rights reserved under the Copyright Laws of the United States.

Contractor/Manufacturer is:

Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.