diguyGraphicsShaderInstance

Generated from diguyGraphicsShaderInstance.h

DI-Guy API Version 12.5.1

This file was automatically generated from diguyGraphicsShaderInstance.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

This class implements shader instances for use with shader programs for a character.

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 GLSL shader uniform variables.

Also see diguyGraphicsShaderProgram.

class diguyGraphicsShaderInstance

class BDI_DECLSPEC_diguy diguyGraphicsShaderInstance
{
public:
    
    diguyGraphicsShaderTechnique* get_shader_technique();
#ifdef CPLUSPLUS_ONLY
    const float* get_shader_matrix_data_ptr();
#endif
    diguyCharacter* get_character();
#ifdef CPLUSPLUS_ONLY
    virtual int bind();
    virtual int unbind();
#endif
    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);
    void reset_variables_to_initial_values();
    void reset_variables_to_program_defaults();
    int set_variable_float(const char* name, float value, int set_current = 1, int set_initial = 0, float blend_time = 0.0f);
    int set_variable_vec2(const char* name, float x, float y, int set_current = 1, int set_initial = 0, float blend_time = 0.0f);
    int set_variable_vec3(const char* name, float x, float y, float z, int set_current = 1, int set_initial = 0, float blend_time = 0.0f);
    int set_variable_vec4(const char* name, float x, float y, float z, float w, int set_current = 1, int set_initial = 0, float blend_time = 0.0f);
    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);
    diguyGraphicsShaderProgram* get_shader_program();
    int get_num_link_matrices();
    virtual int update_link_matrices(int num_matrices,
        const float* mat_data);

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 diguyGraphicsShaderInstance::get_shader_technique

Prototype:
diguyGraphicsShaderTechnique* get_shader_technique();
Description:

This function returns the shader technique this shader instance is associated with.
Returns:

pointer to type diguyGraphicsShaderTechnique; should never be NULL
Callable From:

C++

function diguyGraphicsShaderInstance::get_shader_matrix_data_ptr

Prototype:
const float* get_shader_matrix_data_ptr();
Description:

This function returns a pointer to shader matrix data. This is the same pointer that is passed into bind_link_matrices().

The returned pointer should not be cached for later used, as it may change multiple times during the lifetime of this shader instance.
Returns:

pointer to first value in array of floats
Callable From:

C++

function diguyGraphicsShaderInstance::get_character

Prototype:
diguyCharacter* get_character();
Description:

This function returns a pointer to the character that this shader instance is associated with.
Returns:

pointer to type diguyCharacter; may be NULL
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 diguyGraphicsShaderInstance::bind

Prototype:
virtual int bind();
Description:

This function will be called by DI-Guy when it is time for the object that this shader instance is attached to to be rendered. This happens during the Draw Stage, just before the geometry of a character or scene object is to be rendered.

Any instance level shader control variables should be set in this function. Instance level variables will affect only shader operations in which this instance is active. Variables that should affect the overall program of a shader should be set in diguyGraphicsShaderProgram::bind().
Immediate Mode:

Immediate mode renderers usually do 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 diguyGraphicsShaderInstance::unbind

Prototype:
virtual int unbind();
Description:

This function will be called by DI-Guy when the object this shader is attached to is done being rendered.

This happens during the Draw Stage, just after the geometry of a character has been rendered.

Any shader variables bound in bind() should be unbound here.
Immediate Mode:

Immediate mode renderers usually do 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)

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.

Instance shader variables are not shared between instances. Variables that should affect all instances of the program this instance is associated with should be set at the shader program level, using equivalent functions in diguyGraphicsShaderProgram.

function diguyGraphicsShaderInstance::get_num_variables

Prototype:

int get_num_variables();

function diguyGraphicsShaderInstance::get_variable_name_at_index

Prototype:

const char* get_variable_name_at_index(int index);

function diguyGraphicsShaderInstance::has_variable

Prototype:

int has_variable(const char* name);

function diguyGraphicsShaderInstance::get_variable_type

Prototype:

const char* get_variable_type(const char* name);

function diguyGraphicsShaderInstance::reset_variables_to_initial_values

Prototype:

void reset_variables_to_initial_values();

function diguyGraphicsShaderInstance::reset_variables_to_program_defaults

Prototype:

void reset_variables_to_program_defaults();

function diguyGraphicsShaderInstance::set_variable_float

Prototype:

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

function diguyGraphicsShaderInstance::set_variable_vec2

Prototype:

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

function diguyGraphicsShaderInstance::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, float blend_time = 0.0f);

function diguyGraphicsShaderInstance::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, float blend_time = 0.0f);

function diguyGraphicsShaderInstance::set_variable_int

Prototype:

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

function diguyGraphicsShaderInstance::get_variable_float

Prototype:

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

function diguyGraphicsShaderInstance::get_variable_vec2

Prototype:

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

function diguyGraphicsShaderInstance::get_variable_vec3

Prototype:

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

function diguyGraphicsShaderInstance::get_variable_vec4

Prototype:

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

function diguyGraphicsShaderInstance::get_variable_int

Prototype:

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

Deprecated Functions

The following functions are deprecated.

As these functions may disappear in a future version of DI-Guy, it is recommended that you remove calls to these functions from your application.

function diguyGraphicsShaderInstance::get_shader_program

Prototype:
diguyGraphicsShaderProgram* get_shader_program();
Deprecated Functions: changed due to API restructuring

This function returns the shader program this shader instance is associated with.
Returns:

pointer to type diguyGraphicsShaderProgram; should never be NULL
Callable From:

C++

function diguyGraphicsShaderInstance::get_num_link_matrices

Prototype:
int get_num_link_matrices();
Description:

This function has been deprecated. Skinned matrices are now bound at a per shape level.

This function returns the number of link matrices this instance needs to support. This is useful to know when requesting resources during shader initialization (e.g., requesting uniform variable space).

This same number will be passed to update_link_matrices() and bind_link_matrices().
Returns:

number of link matrices needed by this shader instance
Callable From:

C++

function diguyGraphicsShaderInstance::update_link_matrices

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

This function has been deprecated as of DI-Guy 12. Skinned matrices are now updated at a per shape level.

This function will be called by DI-Guy when the matrix data of a character's links needs to be updated. Scene graph renderers will queue up this data to be sent to the graphics card at the appropriate time.

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 not override this function, but instead use bind_link_matrices() during the Draw Stage.
Scene Graph:

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

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

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.