diguyGraphicsShaderProgram

Generated from diguyGraphicsShaderProgram.h

DI-Guy API Version 12.5.1

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

Includes: diguy_constants.h | declspec_diguy.h

Contents:

Alphabetical Index

Link against: libdiguy_graphics_api

enumeration diguyGraphicsShaderQualityLevel

typedef enum
{
	DIGUY_GRAPHICS_SHADER_QUALITY_UNKNOWN = -1,
	DIGUY_GRAPHICS_SHADER_QUALITY_UNLIT = 0,
	DIGUY_GRAPHICS_SHADER_QUALITY_PER_VERTEX = 1,
	DIGUY_GRAPHICS_SHADER_QUALITY_PER_PIXEL = 2,
	DIGUY_GRAPHICS_SHADER_QUALITY_PER_PIXEL_BUMP_MAPPED = 3,
	DIGUY_GRAPHICS_SHADER_QUALITY_MAX
} diguyGraphicsShaderQualityLevel;
Description:

This enumeration lists the quality level of various shader programs that DI-Guy might create.

int diguyApp::set_max_character_shader_quality_level(int quality_level); int diguyApp::set_max_scene_object_shader_quality_level(int quality_level);

enumeration diguyGraphicsShaderProgramType

typedef enum
{
	DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_UNKNOWN = -1,
	DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_GENERAL =  0,
	DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_SKIN,
	DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_REFLECTOR

} diguyGraphicsShaderProgramType;
Description:

This enumeration lists the types of shader programs that DI-Guy might request.
DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_GENERAL
DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_SKIN
DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_REFLECTOR

This class implements shader programs for use with DI-Guy character graphics.

Shader programs are shared among all characters that use the shader program. Any variables used in a shader program should therefore apply to all characters using the shader.

Shader instances are not shared. Each character that has a shader program assigned to it will have a private shader instance in which variables specific to the character or its instance can be stored. A common case for this is current values of shader uniform variables.

Also see diguyGraphicsShaderInstance.

class diguyGraphicsShaderProgram

class BDI_DECLSPEC_diguy diguyGraphicsShaderProgram
{
public:
    const char* get_name();
    const char* get_vertex_shader_filename();
    const char* get_pixel_shader_filename();
    diguyGraphicsShaderProgramType get_shader_type();
    diguyGraphicsShaderQualityLevel get_quality_level();
    void derive_diguy_shader_source_filename(char* result,
        int result_max_len,
        const char* shader_base_name,
        const char* shader_language,
        const char* shader_type,
        int include_diguy_default_shader_directory);
    void print_shader_info_to_log();
    int load();
     int set_textures_used_bitmask(int texture_bitmask);
    int get_textures_used_bitmask();
    
#ifdef CPLUSPLUS_ONLY
    virtual int load_vertex_shader_source(const char* filename_base);
    virtual int load_pixel_shader_source(const char* filename_base);
    virtual int reload();
    virtual int link();
    virtual int get_loaded();
    virtual int get_linked();
    virtual int get_valid();
    virtual int bind();
    virtual int unbind();
    virtual int bind_link_matrices(int num_matrices,
        const float* mat_data);
    virtual int bind_color_array(int num_colors,
        const float* color_data);
    virtual int bind_uniform_with_location(int location,
        const char* name,
        int value_size,
        float* values);
    virtual int bind_uniform_with_location(int location,
        const char* name,
        int value_size,
        int* values);
    virtual int get_attrib_bind_location(const char* name);
    virtual int get_uniform_bind_location(const char* name);
#endif
    
    int get_num_additional_feature_names();
    const char * get_additional_feature_name(int index);
    int has_additional_feature(const char * name);
    static int get_transposed_matrix_data();
    
    static int get_use_4x3_shader_matrix_data();
    
    int get_num_variables();
    const char* get_variable_name_at_index(int index);
    int has_variable(const char* name);
    const char* get_variable_type(const char* name);
    int set_variable_float(const char* name, float value, int set_current = 1, int set_initial = 0);
    int set_variable_vec2(const char* name, float x, float y, int set_current = 1, int set_initial = 0);
    int set_variable_vec3(const char* name, float x, float y, float z, int set_current = 1, int set_initial = 0);
    int set_variable_vec4(const char* name, float x, float y, float z, float w, int set_current = 1, int set_initial = 0);
    int set_variable_int(const char* name, int value, int set_current = 1, int set_initial = 0);
    int get_variable_float(const char* name, float* value, int get_current = 1);
    int get_variable_vec2(const char* name, float* x, float* y, int get_current = 1);
    int get_variable_vec3(const char* name, float* x, float* y, float* z, int get_current = 1);
    int get_variable_vec4(const char* name, float* r, float* g, float* b, float* a, int get_current = 1);
    int get_variable_int(const char* name, int* value, int get_current = 1);

Accessor Functions

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

All are Callable From:

C++
Script

function diguyGraphicsShaderProgram::get_name

Prototype:
const char* get_name();
Returns:

name of the shader This pointer will never be NULL.

function diguyGraphicsShaderProgram::get_vertex_shader_filename

Prototype:
const char* get_vertex_shader_filename();
Returns:

the vertex filename of the shader This pointer will never be NULL.

function diguyGraphicsShaderProgram::get_pixel_shader_filename

Prototype:
const char* get_pixel_shader_filename();
Returns:

the pixel shader filename of the shader This pointer will never be NULL.

function diguyGraphicsShaderProgram::get_shader_type

Prototype:
diguyGraphicsShaderProgramType get_shader_type();
Returns:

program type of the shader; see diguyGraphicsShaderProgramType

function diguyGraphicsShaderProgram::get_quality_level

Prototype:
diguyGraphicsShaderQualityLevel get_quality_level();
Returns:

the quality level type of the shader; see diguyGraphicsShaderQualityLevel

function diguyGraphicsShaderProgram::derive_diguy_shader_source_filename

Prototype:
void derive_diguy_shader_source_filename(char* result,
    int result_max_len,
    const char* shader_base_name,
    const char* shader_language,
    const char* shader_type,
    int include_diguy_default_shader_directory);
Description:

This function derives filenames for shader programs from the provided information.
Arguments:

result string buffer in which result should be placed
result_max_len size of supplied string buffer; too small will result in a truncated filename
shader_base_name base name of shader program; e.g. "diguy_character"
shader_language language of shader program; e.g. "glsl" or "hlsl"
shader_type shader program type; e.g. "vert" or "frag"
include_diguy_default_shader_directory pass 1 to include the default DI-Guy shader directory in the filename; pass 0 to return the filename only with no path

The constructed filename has the format "(shader_base_name)_(shader_language).(shader_type)"; e.g., "diguy_character_glsl.vert".

The DI-Guy shader directory defaults to $DIGUYgeometryshaders.
Returns:

filename result in the result argument

function diguyGraphicsShaderProgram::print_shader_info_to_log

Prototype:
void print_shader_info_to_log();
Description:

Prints information about the shader to the log.

function diguyGraphicsShaderProgram::load

Prototype:
int load();
Description:

Forces the underlying shader to load. Returns 0 on sucess.

Texture Management

function diguyGraphicsShaderProgram::set_textures_used_bitmask

Prototype:
 int set_textures_used_bitmask(int texture_bitmask);
Description:

Sets a bit mask consisting of diguyTextureMapMasks or'd together to specify what textures should bind when this shader is active.

See %DIGUY%\programming_examples\diguy_graphics_api\ogl_examples\common\diguyOglGraphicsShaderProgram.cpp for an example of usage. By default in the graphics API we attempt to bind all textures.

function diguyGraphicsShaderProgram::get_textures_used_bitmask

Prototype:
int get_textures_used_bitmask();
Returns:

the current or'd together list of diguyTextureMapMasks that this shader attempts to bind. Defaults to DIGUY_TEXTURES_MAP_MASK_ALL (0xffffffff)

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 diguyGraphicsShaderProgram::load_vertex_shader_source

Prototype:
virtual int load_vertex_shader_source(const char* filename_base);
Description:

This function will be called by DI-Guy when it is time for the vertex part of this shader to be loaded and compiled. The utility function derive_diguy_shader_source_filename() can be used to convert the passed filename_base to an actual filename.

For example, assume that m_vertex_shader_filename is a character array of 512 bytes. The following function call would derive an appropriate vertex shader filename:
derive_diguy_shader_source_filename(m_vertex_shader_filename,
    511,
    filename_base,
    "glsl",
    "vert",
    1);
This function is called during the Build Stage.
Returns:

0 to indicate load was successful, -1 otherwise
Immediate Mode:

Immediate mode renderers usually do override this function.
Scene Graph:

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

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

function diguyGraphicsShaderProgram::load_pixel_shader_source

Prototype:
virtual int load_pixel_shader_source(const char* filename_base);
Description:

This function is the pixel shader (AKA fragment shader in OpenGL) equivalent of load_vertex_shader_source().

function diguyGraphicsShaderProgram::reload

Prototype:
virtual int reload();
Description:

This function will be called by DI-Guy if this shader program should be reloaded. The same filenames derived in the load_vertex_shader_source() and load_pixel_shader_source() functions should be used.

This function can be called during the Update Stage.
Returns:

0 to indicate reload was successful, -1 otherwise
Immediate Mode:

Immediate mode renderers usually do override this function.
Scene Graph:

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

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

function diguyGraphicsShaderProgram::link

Prototype:
virtual int link();
Description:

This function will be called by DI-Guy when it is time for the shader program to be linked.

This function is called during the Build Stage after the load_vertex_shader_source() and load_pixel_shader_source() functions.

Once the link has successfully completed shader variable bind indices can be looked up.
Returns:

0 to indicate link was successful, -1 otherwise
Immediate Mode:

Immediate mode renderers usually do override this function.
Scene Graph:

Scene graph renderers can override this function.
Callable From:

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

function diguyGraphicsShaderProgram::get_loaded

Prototype:
virtual int get_loaded();
Description:

Returns whether the shader has been loaded. Note that because a shader has been loaded doesn't mean that it is valid. See get_valid().
Returns:

1 if shader has been loaded; 0 if not

function diguyGraphicsShaderProgram::get_linked

Prototype:
virtual int get_linked();
Description:

Returns whether the shader has been linked. Note that this only means that it is been attempted to link the shader. The link may have failed, and the shader not be valid. See get_valid().
Returns:

1 if shader has been linked; 0 if not

function diguyGraphicsShaderProgram::get_valid

Prototype:
virtual int get_valid();
Description:

Returns whether shader is valid. An invalid shader will not work correctly, leaving graphics that use this shader unshaded. What this will look like visually in undetermined.
Returns:

1 if shader is valid; 0 if not

function diguyGraphicsShaderProgram::bind

Prototype:
virtual int bind();
Description:

This function will be called by DI-Guy when this program is being bound for rendering.

It is during this function call that program level shader variables should be set. Program level variables will affect all shader operations in which this program is active. Variables that should affect specific instances of a shader should be set in diguyGraphicsShaderInstance::bind().

One example in the DI-Guy reference shaders is the ufrm_textures_enabled variable. Setting it to 0 will prevent textures from being applied during the shader program run.

This happens during the Draw Stage.
Immediate Mode:

Immediate mode renderers can override this function.
Scene Graph:

Scene graph renderers usually do not override this function; the renderer will typically do this internally. If shader variables need to be bound, however, this function should be overridden.
Callable From:

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

function diguyGraphicsShaderProgram::unbind

Prototype:
virtual int unbind();
Description:

In general variables that were set in bind() should be unset or unbound here.

This happens during the Draw Stage.
Immediate Mode:

Immediate mode renderers can override this function.
Scene Graph:

Scene graph renderers usually do not override this function; the renderer will typically do this internally. If the bind() function was overridden, however, this function probably should be, too.
Callable From:

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

function diguyGraphicsShaderProgram::bind_link_matrices

Prototype:
virtual int bind_link_matrices(int num_matrices,
    const float* mat_data);
Description:

This function will be called by DI-Guy when the matrix data of a character's links needs to be sent to the graphics card.

For GLSL-based shaders, these values are typically passed into the vertex shader via uniform variables.

Note that the format of the data in mat_data will be affected by the bdiGraphicsInitGraphicsAPI variable transpose_shader_matrices value.
Immediate Mode:

Immediate mode renderers usually do override this function.
Scene Graph:

Scene graph renderers usually do not override this function, but instead use diguyGraphicsShape::get_shader_matrix_data() during the Update Stage.
Callable From:

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

function diguyGraphicsShaderProgram::bind_color_array

Prototype:
virtual int bind_color_array(int num_colors,
    const float* color_data);
Description:

This function will be called by DI-Guy when the color data of a character's links needs to be sent to the graphics card.

For GLSL-based shaders, these values are typically passed into the vertex shader via uniform variables.
Callable From:

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

function diguyGraphicsShaderProgram::bind_uniform_with_location

Prototype:
virtual int bind_uniform_with_location(int location,
    const char* name,
    int value_size,
    float* values);
Description:

These functions will be called by DI-Guy when there is a shader uniform that needs to be updated and sent to the graphics card.

For GLSL-based shaders, these values are typically passed into the shader via uniform variables. This function will get repeatedly invoked if a character is using per shape materials. See diguyGraphicsShape::set_material_parameter_4f() for more details.
Callable From:

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

location the shader uniform to feed this data to, this is the value that was retrieved via a call to get_ufrm_bind_location()
name string representation of the uniform, useful for debugging
value_size number of ints or floats to send to the video card
values pointer to ints or floats to send to the video card

function diguyGraphicsShaderProgram::bind_uniform_with_location

Prototype:

virtual int bind_uniform_with_location(int location,
    const char* name,
    int value_size,
    int* values);

function diguyGraphicsShaderProgram::get_attrib_bind_location

Prototype:
virtual int get_attrib_bind_location(const char* name);
Description:

This function will be called by DI-Guy when core code is attempting to identify the capabilities of the end users shader. Currently attribute locations are unused. Return -1 to disable any functionality.

function diguyGraphicsShaderProgram::get_uniform_bind_location

Prototype:
virtual int get_uniform_bind_location(const char* name);
Description:

This function will be called by DI-Guy when core code is attempting to identify the capabilities of the end users shader. This needs to be implemented to enable per shape advanced materials. Return -1 to disable any functionality.

Shader Features

Shader config files have an optional list of additional features that can be used to data drive program loading.

function diguyGraphicsShaderProgram::get_num_additional_feature_names

Prototype:

int get_num_additional_feature_names();

function diguyGraphicsShaderProgram::get_additional_feature_name

Prototype:

const char * get_additional_feature_name(int index);

function diguyGraphicsShaderProgram::has_additional_feature

Prototype:

int has_additional_feature(const char * name);

Matrix Format Functions

function diguyGraphicsShaderProgram::get_transposed_matrix_data

Prototype:
static int get_transposed_matrix_data();
Returns:

The value specified in bdiGraphicsInitGraphicsAPI.transpose_shader_matrices. Indicates if DI-Guy will attempt to transpose 4x4 matrices before sending to video card.

function diguyGraphicsShaderProgram::get_use_4x3_shader_matrix_data

Prototype:
static int get_use_4x3_shader_matrix_data();
Returns:

The value specified in bdiGraphicsInitGraphicsAPI.use_4x3_shader_matrices. Indicates if DI-Guy is sending 4x3 matrix data instead of 4x4 data.

Shader Variables

For GLSL shaders, these variables are represented internally as uniform variables. DI-Guy reference shaders commonly use the prefix "ufrm_" for their uniform variables.

Program level shader variables are shared between all shader instances that use this program. Variables that should affect specific instances associated with individual objects (typically characters and scene objects) should be set at the shader instance level, using equivalent functions in diguyGraphicsShaderInstance.

function diguyGraphicsShaderProgram::get_num_variables

Prototype:

int get_num_variables();

function diguyGraphicsShaderProgram::get_variable_name_at_index

Prototype:

const char* get_variable_name_at_index(int index);

function diguyGraphicsShaderProgram::has_variable

Prototype:

int has_variable(const char* name);

function diguyGraphicsShaderProgram::get_variable_type

Prototype:

const char* get_variable_type(const char* name);

function diguyGraphicsShaderProgram::set_variable_float

Prototype:

int set_variable_float(const char* name, float value, int set_current = 1, int set_initial = 0);

function diguyGraphicsShaderProgram::set_variable_vec2

Prototype:

int set_variable_vec2(const char* name, float x, float y, int set_current = 1, int set_initial = 0);

function diguyGraphicsShaderProgram::set_variable_vec3

Prototype:

int set_variable_vec3(const char* name, float x, float y, float z, int set_current = 1, int set_initial = 0);

function diguyGraphicsShaderProgram::set_variable_vec4

Prototype:

int set_variable_vec4(const char* name, float x, float y, float z, float w, int set_current = 1, int set_initial = 0);

function diguyGraphicsShaderProgram::set_variable_int

Prototype:

int set_variable_int(const char* name, int value, int set_current = 1, int set_initial = 0);

function diguyGraphicsShaderProgram::get_variable_float

Prototype:

int get_variable_float(const char* name, float* value, int get_current = 1);

function diguyGraphicsShaderProgram::get_variable_vec2

Prototype:

int get_variable_vec2(const char* name, float* x, float* y, int get_current = 1);

function diguyGraphicsShaderProgram::get_variable_vec3

Prototype:

int get_variable_vec3(const char* name, float* x, float* y, float* z, int get_current = 1);

function diguyGraphicsShaderProgram::get_variable_vec4

Prototype:

int get_variable_vec4(const char* name, float* r, float* g, float* b, float* a, int get_current = 1);

function diguyGraphicsShaderProgram::get_variable_int

Prototype:

int get_variable_int(const char* name, int* value, int get_current = 1);

Private Functionality

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.

`result`	string buffer in which result should be placed
`result_max_len`	size of supplied string buffer; too small will result in a truncated filename
`shader_base_name`	base name of shader program; e.g. "diguy_character"
`shader_language`	language of shader program; e.g. "glsl" or "hlsl"
`shader_type`	shader program type; e.g. "vert" or "frag"
`include_diguy_default_shader_directory`	pass 1 to include the default DI-Guy shader directory in the filename; pass 0 to return the filename only with no path

`location`	the shader uniform to feed this data to, this is the value that was retrieved via a call to get_ufrm_bind_location()
`name`	string representation of the uniform, useful for debugging
`value_size`	number of ints or floats to send to the video card
`values`	pointer to ints or floats to send to the video card