diguyGraphicsShape.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2015 VT MAK
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************/
#ifndef __diguyGraphicsShape_H
#define __diguyGraphicsShape_H

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

#ifdef CPLUSPLUS_ONLY
#include <diguy_constants.h>

class bdiShape;
class diguyCharacter;
class diguyGraphicsFile;
class diguyGraphicsLink;
class diguyGraphicsMesh;
class diguyGraphicsShape;
class diguyGraphicsState;


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

#endif

#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyGraphicsShape
{

public:


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns the name of the shape.  The returned pointer
         **    will never be NULL.
         **
         *b  Returns:
         **
         **    name of the shape as C string
         */
        const char* get_name();

        /*l
         *b  Description:
         **
         **    All shapes are assigned a unique identifier, or uid.  This function
         **    returns this shape's uid.
         **
         **    *Note*: unique identifiers can change between DI-Guy runs.
         **
         *b  Returns:
         **
         **    unique identifier of object
         */
        long get_uid();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the diguyCharacter to which this
         **    shape belongs.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacter
         */
        diguyCharacter* get_character();


        /*l
         *b  Description:
         **
         **    This function returns the name of the shape set of which this shape
         **    is a part.
         **
         **    A shape set is a collection of shapes that are related, coming from
         **    a set of related geometry files, sometimes one file per LOD.
         **
         **    A shape is a collection of parts each representing the same thing
         **    at varying levels of detail.
         **
         **    For example, in its config files DI-Guy has a shape set named
         **    "firefighter", which references five OpenFlight files named
         **    firefighter_LOD1.flt through firefighter_LOD5.flt.  The firefighter
         **    shape set contains separate shapes for the head, arms, legs, etc.,
         **    at five different levels of detail.
         **
         **    Use the function get_shape_set_filename_for_lod() to get the actual
         **    geometry filenames that should be used for each LOD.
         **
         *b  Returns:
         **
         **    shape set of shape as C string
         */
        const char* get_shape_set_name();

        /*l
         *b  Description:
         **
         **    This function returns the name of the shape.  This name identifies
         **    which pieces of geometry out of the shape set should comprise the
         **    shape.
         **
         *b  Returns:
         **
         **    shape name of shape as C string
         */
        const char* get_shape_set_shape_name();

        /*l
         *b  Description:
         **
         **    This function returns the name of the link to which this shape is
         **    typically attached.
         **
         **    Use the function get_link() to get a pointer to the actual link to
         **    which this shape is attached.
         **
         *b  Returns:
         **
         **    name of recommended attachment link as C string
         */
        const char* get_recommended_attachment_link_name();

        /*l
         *b  Description:
         **
         **    This function returns how many LODs this shape has.  This will be a
         **    number between 1 and 7.
         **
         *b  Returns:
         **
         **    number of LODs
         */
        int get_num_lods();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function returns the LOD ranges of this shape.  The returned
         **    pointer points to an array of eight floats, which represent ranges
         **    in meters at which LODs should be shown.
         **
         *b  Returns:
         **
         **    LOD ranges
         **
         *b  Only Callable From C++
         */
        float* get_lod_ranges();

#endif

        /*l
         *b  Description:
         **
         **    This function returns the most recent lod setting as set by
         **    set_graphics_lod(), or as set by
         **    diguyCharacter::set_graphics_lod().
         **
         *b  Returns:
         **
         **    LOD index; integer from 1 to get_num_lods()
         */
        int get_graphics_lod();

        /*l
         *b  Description:
         **
         **    This function returns the filename of the geometry file from which
         **    the shape is read for a specific LOD.
         **
         *b  Arguments:
         **
         *a    lod - level of detail; a number between 1 and get_num_lods()
         **
         *b  Returns:
         **
         **    geometry filename as C string
         */
        const char* get_shape_set_filename_for_lod(int lod);

        /*l
         *b  Description:
         **
         **    This function returns the number of low-level geometry meshes that
         **    comprise this shape.
         **
         *b  Arguments:
         **
         *a    lod - level of detail; a number between 1 and get_num_lods()
         **
         *b  Returns:
         **
         **    number of meshes in this shape
         */
        int get_num_meshes(int lod);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to one of the low-level geometry
         **    mesh objects that comprise this shape.
         **
         *b  Arguments:
         **
         *a    index - index of mesh; a number between 0 and get_num_meshes() - 1
         *a    lod   - level of detail; a number between 1 and get_num_lods()
         **
         *b  Returns:
         **
         **    pointer to object of type diguyGraphicsMesh; NULL on error
         */
        diguyGraphicsMesh* get_mesh_at_index_for_lod(int index, int lod);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the link to which this shape is
         **    actually attached.
         **
         *b  Arguments:
         **
         *a    index - index of mesh; a number between 0 and get_num_meshes() - 1
         *a    lod   - level of detail; a number between 1 and get_num_lods()
         **
         *b  Returns:
         **
         **    pointer to object of type diguyGraphicsMesh; NULL on error
         */
        diguyGraphicsLink* get_link();

        /*l
         *b  Description:
         **
         **    This function returns the name of the DI-Guy motion data variable
         **    that controls whether this shape should be visible.
         **
         **    The returned pointer will be NULL if there is no associated
         **    variable.
         **
         *b  Returns:
         **
         **    name of the variable; NULL if there is no variable
         */
        const char* get_switch_var_name();

        /*l
         *b  Description:
         **
         **    This function returns the value of the DI-Guy motion data variable
         **    for which the shape should be visible.
         **
         **    Note that the variable in the motion data is a float, but gets cast
         **    to an integer and compared against this number during shape
         **    updates.
         **
         *b  Returns:
         **
         **    number representing value for which shape should be visible
         */
        int get_switch_value();

        /*l
         *b  Description:
         **
         **    This function returns whether this shape should currently be hidden
         **    or shown, based on the value of the shape's switch variable (if
         **    any).
         **
         *b  Returns:
         **
         **    1 if shape is hidden, 0 if not
         */
        int get_is_hidden();

        int set_is_hidden(int hidden);

        /*l
         *b  Description:
         **
         **    This function returns the geometry file from which geometry for the
         **    shape was read.  Each LOD of the shape may potentially come from a
         **    different file.
         **
         **    Note that if a diguyGraphicsFile create function has not been
         **    registered with a call to diguy_graphics_set_file_create_func(),
         **    this function will return NULL.
         **
         *b  Arguments:
         **
         *a    lod   - level of detail; a number between 1 and get_num_lods()
         **
         *b  Returns:
         **
         **    object of type diguyGraphicsFile
         */
        diguyGraphicsFile* get_diguy_graphics_file(int lod);

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function returns a pointer to an object that represents the
         **    geometry for the shape.  The returned object is an object that has
         **    been returned by a previous call to diguyGraphicsFile::find_part(),
         **    and can be safely cast to the type of object that has been so
         **    returned.
         **
         **    Note that if a diguyGraphicsFile create function has not been
         **    registered with a call to diguy_graphics_set_file_create_func(),
         **    this function will return NULL.
         **
         *b  Arguments:
         **
         *a    lod   - level of detail; a number between 1 and get_num_lods()
         **
         *b  Returns:
         **
         **    generic object which must be cast appropriately
         **
         *b  Only Callable From C++
         */
        void* get_diguy_graphics_file_part(int lod);

#endif

        /*l
         *b  Description:
         **
         **    Some shapes have meshes that have multiple selectable graphics
         **    states, including materials and textures.  This function returns
         **    the value that specifies which graphics state to use for meshes of
         **    this shape.
         **
         **    This is different than get_switch_value(), which returns the value
         **    of the switch that controls whether or not meshes of this state are
         **    shown.
         **
         *b  Returns:
         **
         **    value of state switch; -1 if there is no state switch
         */
        int get_graphics_state_switch_index();

        /*l
         *b  Description:
         **
         **    Returns the number of switched graphics states available to this
         **    shape.  See get_graphics_state_switch_index().
         **
         *b  Returns:
         **
         **    number of switched graphics states
         */
        int get_num_switched_graphics_states();

        /*l
         *b  Description:
         **
         **    Returns the graphics state associated with the passed switch value.
         **
         *b  Returns:
         **
         **    pointer to type diguyGraphicsState
         */
        diguyGraphicsState* get_switched_graphics_state(int switch_value = -1);

        /*l
         *b  Description:
         **
         **    Returns in the passed pointers the unique color of this shape. All
         **    shapes in a DI-Guy appearance are assigned a unique RGB color that
         **    can be used in pick/selection operations.
         **
         **    Also see diguyScenario::map_color_to_impact().
         **
         **    See programming_examples/diguy_graphics_api/ogl_examples/intersection_test
         **    for an example of its usage.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_unique_color(unsigned char* r,
                unsigned char* g,
                unsigned char* b);

        /*l
         *b  Description:
         **
         **    This function identifies if this shape has skinned data.  Scene
         **    graph renderers will need to know this in the build phase to help
         **    set up the matrix data shader functionality.
         **
         *b  Returns:
         **
         **    1 if contains at lease one file with skinned data, 0 if not
         */
        int get_contains_skinned_file();

        /*l
         *b  Description:
         **
         **    By default DI-Guy provides three 4 float uniforms at the shape
         **    level that can be used by end users to customize the appearance of
         **    characters via shaders and misc textures.  You can see a
         **    demonstration of this in the Exface_sales_demo.dss file where an
         **    additional texture is used. The uniforms are named:
         **
         *-    -"ufrm_blood_color"
         *-    -"ufrm_grime_color"
         *-    -"ufrm_glow_color"
         **
         *b   Example:
         **
         *e   local character = this_scenario:get_character_at_index(0);
         *e   local link = character:get_link_at_index(0);
         *e   local shape = link:find_shape_by_class_type("head");
         *e   shape:set_material_parameter_4f("ufrm_blood_color",1,.1,.1,.5, 1);
         */
        int set_material_parameter_4f(const char* parameter_name,
                float x, float y, float z, float w,
                float blend_time = 0.0);

        /*l
         *b  Description:
         **
         **    Allow access to the current values of a material parameter, accounting 
         **    for value blending. Returns -1 if the parameter can't be found.
         */
        int get_material_parameter_4f(const char* parameter_name,
                float* x, float* y, float* z, float* w);

        /*l
         *b  Description:
         **
         **    Returns a char * of length get_variation_texture_size() that represents 
         **    the pixels in a unique per shape texture. Typically a Retained mode 
         **    renderer would need to use this to load a state node with the texture
         **    see diguyOsgGraphicsShape.cpp for an example. For an immediate mode 
         **    renderer we push the texture to the object via update_variation_texture()
         */
        unsigned char * get_variation_texture();

        int get_variation_texture_size();

        int get_num_variations();

        const char * get_variation_name(int variation_index);

        int set_variation_index(int variation_index);

        int get_has_custom_variation();

        int get_num_variation_components();

        const char * get_variation_component_name(int index);

        int get_variation_component_index(const char * name);
        
        int set_variation_component_value(int index, float color_shift_r, float color_shift_g, float color_shift_b);
        
        int set_state_switch_index(int index);


#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function is typically called by scene graph renderers as part
         **    of diguyGraphicsShape::update().  Scene graph renderers should
         **    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.
         **
         *b  Callable From:
         **
         *-    C++
         */
        int get_shader_matrix_data(int* num_matrixes, const float** matrix_data);

#endif

        /*l
         *b  Description:
         **
         **     Returns the transpose state of the shader matrices.
         **
         *b  Returns:
         **
         **    1 if shader matrices are transposed, 0 otherwise.
         */
        int get_are_shader_matrices_transposed();


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

        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when it is time for
         **    renderer-specific shape objects to be created.  All information
         **    necessary to build the shape should be available via the Accessor
         **    Functions above when this function is called.
         **
         **    The build() function for the link to which a shape is attached
         **    will be called before the shape's build() function.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers can override this function, to create a
         **    pre-compiled object that expedites the draw().  Display lists in
         **    OpenGL are an example of this.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function, to create
         **    scene graph nodes that will hold geometry nodes of meshes attached
         **    to the shape.
         **
         **    The following nodes are typically created:
         **
         *-    - a switch node to control showing and hiding of the shape
         *-    - an LOD node to control which meshes are shown due to
         *-      LOD calculations
         *-    - a geometry parent or group-type object to which mesh
         *-      nodes can be attached
         **
         **    The scene graph nodes created by this function should be attached
         **    to the nodes of the link to which the shape is attached.   Use the
         **    get_link() function to get a pointer to the link.
         **
         **    In addition, the scene graph objects of meshes attached to the
         **    shape should be retrieved and attached to the shape's nodes.  Use
         **    the get_mesh_at_index_for_lod() function to get pointers to the
         **    meshes.
         **
         *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 the
         **    renderer-specific shape objects created during the build() call to
         **    be destroyed.
         **
         **    The unbuild() function for the shape will be called before the
         **    unbuild() function of the link to which the shape is attached.
         **
         *i  Immediate Mode:
         **
         **    Scene graph renderers can override this function, to destroy the
         **    scene graph nodes created by build().
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function, to
         **    destroy the scene graph nodes 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 it is time for
         **    renderer-specific shape objects created during the build() call to
         **    be updated with new data.
         **
         **    Shape updates control whether the shape is visible based on motion
         **    data.  The DI-Guy Graphics software looks at the switch value and
         **    calls show() or hide() as appropriate, so it is likely that this
         **    function does not need to be overridden in immediate mode.
         **
         **    The update() function for the link to which a shape is attached
         **    will be called before the shape's update() function.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do not override this function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers should override this function if they are
         **    supporting skinned characters.  Each skinned shape can potentially
         **    have different uniforms that need to be sent to the video card; see
         **    get_shader_matrix_data().
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      Update Stage)
         */
        virtual void update();

        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when the shape should be
         **    shown, typically due to a change in the motion data that controls
         **    the switch.  See get_switch_var_name() and get_switch_value().
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do not override this function.
         **    DI-Guy does not call the draw() function of hidden shapes.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function, to update
         **    the state of the switch node created during the build() call.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      Update Stage)
         */
        virtual void show();

        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when the shape should be
         **    hidden, typically due to a change in the motion data that controls
         **    the switch.  See get_switch_var_name() and get_switch_value().
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do not override this function.
         **    DI-Guy does not call the draw() function of hidden shapes.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function, to update
         **    the state of the switch node created during the build() call.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      Update Stage)
         */
        virtual void hide();

        // TODO MarcM Documentation
        virtual void instancing_state_changed(int val);
        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when it is time for the
         **    geometry of this shape to be drawn.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do not override this function.
         **    The actual draw calls happen in diguyGraphicsMesh::draw() calls.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do not override this function;
         **    drawing is handled automatically by scene graphs.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      Draw Stage)
         */
        virtual void draw(int lod);

        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when the LOD ranges of this
         **    shape need to be updated after the shape has initially been built
         **    in the Build Stage.
         **
         *b  Arguments:
         **
         *a    lod_ranges - new lod ranges for this shape
         **
         **    See diguyScenario::set_default_lod_ranges() for a description of
         **    what will be in the lod_ranges argument.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do not override this function.
         **    Instead, they use the lod passed into the draw() function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers can override this function, to update the
         **    ranges of LOD nodes created in the Build Stage, if any.
         **
         **    If there were LOD-type nodes created in the Build Stage, their
         **    ranges should be updated based on the passed values.
         **
         **    If no LOD-type nodes were created in the Build Stage, this
         **    function should have no effect.
         **
         **    Typically only one of set_graphics_lod_ranges() or
         **    set_graphics_lod() is implemented.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API when the
         *-      DI-Guy API function diguyCharacter::set_lod_ranges() is
         *-      called)
         */
        virtual void set_graphics_lod_ranges(float* ranges);

        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when the LOD of this link
         **    is "manually" set by a diguyCharacter::set_graphics_lod() function
         **    call.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers usually do not override this function.
         **    Instead, they use the lod passed into the draw() function.
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers sometimes override this function, to update
         **    the state of switch nodes created in the Build Stage.
         **
         **    Typically only one of set_graphics_lod_ranges() or
         **    set_graphics_lod() is implemented.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API when the
         *-      DI-Guy API function diguyCharacter::set_graphics_lod() is
         *-      called)
         */
        virtual void set_graphics_lod(int lod);


        /*l
         *b  Description:
         **
         **    Pushes a char * pixel buffer of length num_pixels that represents 
         **    the unique per shape texture. Typically a Immediate mode renderer 
         **    would need to use this to create or update a texture 
         **    see diguyOglGraphicsShape.cpp for an example. For an retained mode 
         **    renderer we have get_variation_texture() as an accessor.
         **    
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      Build Stage)
         */
        virtual void update_variation_texture(int num_pixels, unsigned char * pixel_data);

        /*l
         *b  Description:
         **
         **  Returns the unique color of the character links.  All links in a
         **  DI-Guy appearance are assigned a unique RGB color that can be used
         **  in pick/selection operations.  The data returned in color_data is
         **  an array of length num_colors with 4 floats per entry (r, g, b, a).
         **
         **  See programming_examples/diguy_graphics_api/osg_2_examples/intersection_test
         ** for an example of its usage.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_bind_color_array(int* num_colors, const float** color_data);
        
#endif

#ifdef CPLUSPLUS_ONLY

        // EXPERIMENTAL
        // FIXME: Added to access quats directly instead of shader matricies
        // for Unity optimization.  [Marc 11/22/2013]
        int get_link_to_matrix_table(int* num_matrices, const float** lookup_data);

        int get_bone_index_from_link_index(int link_index);

#endif

        // documentation pending
        int get_has_offset_matrix();
        // documentation pending
        int get_offset_matrix_4x4_ptr(float* matrix, int transpose = 0);
        

/****************************************************************************/
/****************************************************************************/
        int get_has_offset_translation();

        int get_offset_translation(float* tx, float* ty, float* tz);

        int get_has_offset_rotation();

        int get_offset_rotation(float* rz, float* rx, float* ry);

        int get_has_offset_scale();

        int get_offset_scale(float* sx, float* sy, float* sz);

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

#ifdef CPLUSPLUS_ONLY

        bdiShape* get_scripted_object() {return m_scripted_object;}

protected:

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

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

private:

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

        friend class bdiShape;
        friend class bdiGraphicsFactory;

#endif

};


#endif /* __diguyGraphicsShape_H */