diguyGraphicsShaderProgram.h

Go to the documentation of this file.

/*
 *  Copyright (C) 1992-2013 Boston Dynamics
 *  ALL RIGHTS RESERVED.
 *
 *  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 Software 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.
 */

/*********************************************************************/
#ifndef __diguyGraphicsShaderProgram_H
#define __diguyGraphicsShaderProgram_H


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

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

class diguyGraphicsLink;
class diguyGraphicsShaderProgram;
class diguyGraphicsShaderInstance;
class bdiShaderProgram;

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

#endif


/****************************************************************************/
/*l
 *b  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);
 */
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;


/****************************************************************************/
/*l
 *b  Description:
 **
 **    This enumeration lists the types of shader programs that DI-Guy
 **    might request.
 **
 *i    DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_GENERAL
 **
 *i    DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_SKIN
 **
 *i    DIGUY_GRAPHICS_SHADER_PROGRAM_TYPE_REFLECTOR
 **
 */
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;


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyGraphicsShaderProgram
{

public:

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

        /*l
         *b  Returns:
         **
         **    the vertex filename of the shader This pointer will never be NULL.
         */
        const char* get_vertex_shader_filename();

        /*l
         *b  Returns:
         **
         **    the pixel shader filename of the shader This pointer will never be NULL.
         */
        const char* get_pixel_shader_filename();

        /*l
         *b  Returns:
         **
         **    program type of the shader; see diguyGraphicsShaderProgramType
         */
        diguyGraphicsShaderProgramType get_shader_type();

        /*l
         *b  Returns:
         **
         **    the quality level type of the shader; see
         **    diguyGraphicsShaderQualityLevel
         */
        diguyGraphicsShaderQualityLevel get_quality_level();

        /*l
         *b  Description:
         **
         **    This function derives filenames for shader programs from the
         **    provided information.
         **
         *b  Arguments:
         **
         *a    result           - string buffer in which result should be placed
         *a    result_max_len   - size of supplied string buffer; too small will
         *a                       result in a truncated filename
         *a    shader_base_name - base name of shader program; e.g. "diguy_character"
         *a    shader_language  - language of shader program; e.g. "glsl" or
         *a                       "hlsl"
         *a    shader_type      - shader program type; e.g. "vert" or "frag"
         *a    include_diguy_default_shader_directory - pass 1 to include the
         *a                       default DI-Guy shader directory in the filename;
         *a                       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 $DIGUY/geometry/shaders.
         **
         *b  Returns:
         **
         **    filename result in the result argument
         */
        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);

        /*l
         *b  Description:
         **
         **    Prints information about the shader to the log.
         */
        void print_shader_info_to_log();


        /*l
         *b  Description:
         **
         **    Forces the underlying shader to load. Returns 0 on sucess.
         */
        int load();

/*****************************************************************************/
        /*l
         *b  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.
         */
         int set_textures_used_bitmask(int texture_bitmask);

        /*l
         *b  Returns:
         **
         **    the current or'd together list of diguyTextureMapMasks that this
         **    shader attempts to bind.  Defaults to
         **    DIGUY_TEXTURES_MAP_MASK_ALL (0xffffffff)
         */
        int get_textures_used_bitmask();

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

        /*l
         *b  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:
         **
         *e     derive_diguy_shader_source_filename(m_vertex_shader_filename,
         *e             511,
         *e             filename_base,
         *e             "glsl",
         *e             "vert",
         *e             1);
         **
         **    This function is called during the Build Stage.
         **
         *b  Returns:
         **
         **    0 to indicate load was successful, -1 otherwise
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do override this function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Build Stage)
         */
        virtual int load_vertex_shader_source(const char* filename_base);

        /*l
         *b  Description:
         **
         **    This function is the pixel shader (AKA fragment shader in OpenGL)
         **    equivalent of load_vertex_shader_source().
         */
        virtual int load_pixel_shader_source(const char* filename_base);

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    0 to indicate reload was successful, -1 otherwise
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do override this function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Build Stage)
         */
        virtual int reload();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    0 to indicate link was successful, -1 otherwise
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do override this function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers can override this function.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Build Stage)
         */
        virtual int link();

        /*l
         *b  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().
         **
         *b  Returns:
         **
         **    1 if shader has been loaded; 0 if not
         */
        virtual int get_loaded();

        /*l
         *b  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().
         **
         *b  Returns:
         **
         **    1 if shader has been linked; 0 if not
         */
        virtual int get_linked();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    1 if shader is valid; 0 if not
         */
        virtual int get_valid();

        /*l
         *b  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.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers can override this function.
         **
         *i  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.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Draw Stage)
         */
        virtual int bind();

        /*l
         *b  Description:
         **
         **    In general variables that were set in bind() should be unset or
         **    unbound here.
         **
         **    This happens during the Draw Stage.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers can override this function.
         **
         *i  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.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Draw Stage)
         */
        virtual int unbind();


        /*l
         *b  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.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do override this function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do not override this function,
         **    but instead use diguyGraphicsShape::get_shader_matrix_data() during the Update Stage.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Draw Stage)
         */
        virtual int bind_link_matrices(int num_matrices,
                const float* mat_data);

        /*l
         *b  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.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Draw Stage)
         */
        virtual int bind_color_array(int num_colors,
                const float* color_data);

        /*l
         *b  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.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      the Draw Stage)
         **
         *b  Arguments:
         **
         *a    location    - the shader uniform to feed this data to, this is the
         *a                  value that was retrieved via a call to get_ufrm_bind_location()
         *a    name        - string representation of the uniform, useful for debugging
         *a    value_size  - number of ints or floats to send to the video card
         *a    values      - pointer to ints or floats to send to the video card
         */
        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);

        /*l
         *b  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.
         **
         */
        virtual int get_attrib_bind_location(const char* name);

        /*l
         *b  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.
         **
         */
        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);

/*****************************************************************************/
        /*l
         *b  Returns: 
         **
         **    The value specified in bdiGraphicsInitGraphicsAPI.transpose_shader_matrices.
         **    Indicates if DI-Guy will attempt to transpose 4x4 matrices before sending to 
         **    video card.
         */
        static int get_transposed_matrix_data();
        
        /*l
         *b  Returns:
         **
         **    The value specified in bdiGraphicsInitGraphicsAPI.use_4x3_shader_matrices.
         **    Indicates if DI-Guy is sending 4x3 matrix data instead of 4x4 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);


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

#ifdef CPLUSPLUS_ONLY

        bdiShaderProgram* get_internal_data() {return m_internal_data;}

protected:

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

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

private:

        /*l
         **    A pointer to internal data.
         */
        bdiShaderProgram* m_internal_data;

        friend class bdiShaderProgram;
        friend class bdiGeometryFactory;
#endif
};


#endif /* __diguyGraphicsShaderProgram_H */