diguyGraphicsMesh.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 __diguyGraphicsMesh_H
#define __diguyGraphicsMesh_H

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

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

class diguyGraphicsMeshInternalData;
class diguyGraphicsMesh;
class diguyGraphicsShaderProgram;
class diguyGraphicsShaderInstance;
class diguyGraphicsState;


#endif

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyGraphicsMesh
{

public:

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

        /*l
         *b  Description:
         **
         **    All meshs are assigned a unique identifer (uid).
         **    This function returns the uid of the mesh.
         **
         **    *Note*: uids will change between DI-Guy runs.
         **
         *b  Returns:
         **
         **     unique identifier of the object
         */
        long get_uid();

        /*l
         *b  Description:
         **
         **    This function returns the graphics state with which faces in this
         **    mesh should be drawn.  Specific information about material and
         **    texture can then be accessed from this object.
         **
         **    Some meshes may have multiple possible graphics states associated
         **    with them.  In effect this means that depending on a character's
         **    appearance, different textures or material settings may be used.
         **
         **    Call get_num_switched_graphics_states() to get the number of
         **    graphics states that are associated with this mesh.
         **
         **    This function is typically called during the Build stage for
         **    scene graph renderers, when geoset/mesh objects are being
         **    created and their graphics states set.
         **
         *b  Returns:
         **
         **    object of type diguyGraphicsState; NULL on failure
         */
        diguyGraphicsState* get_state(int graphics_state_switch_index = 0);

        /*l
         *b  Description:
         **
         **    This function returns the last bound graphic state object this mesh
         **    used.  There should always be at least one. This can be used by
         **    immediate mode renderers during draw calls to find out more about
         **    the properties of the mesh.
         **
         **    See get_state() for more information on switched graphics states.
         **
         *b  Returns:
         **
         **    object of type diguyGraphicsState; NULL on failure
         */
        diguyGraphicsState* get_current_graphics_state();

        /*l
         *b  Description:
         **
         **    This function returns the number of switched graphics states
         **    this mesh has.  There should always be at least one.
         **
         **    See get_state() for more information on switched graphics states.
         **
         *b  Returns:
         **
         **    number of switched graphics states this mesh has
         */
        int get_num_switched_graphics_states();

        /*l
         *b  Description:
         **
         **    This function returns whether or not the mesh is "skinned".
         **
         **    The position of vertices in a skinned mesh are determined
         **    at run-time by transforming them with multiple link transforms.
         **
         **    It is likely that some type of shader is required to render
         **    the mesh correctly.  The shader recommended for this mesh can be
         **    obtained by calling get_shader_program().
         **
         **    Though they sound similar, skinned meshes and deformable meshes
         **    are different.  The vertices in a deformable mesh have already
         **    been transformed when the draw() function is called; nothing
         **    more needs to be done.  The vertices in a skinned are not ready
         **    to be drawn, as they must first be transformed by a shader.
         **
         *b  Returns:
         **
         **    1 if mesh is skinned, 0 if not, -1 on failure
         */
        int get_is_skinned_mesh();

        /*l
         *b  Description:
         **
         **    This function returns whether or not the mesh is deformable.
         **
         **    The position of vertices in a deformable mesh may shift from
         **    frame to frame and therefore should not be put into a
         **    renderer-specific object that cannot be updated.  (For example,
         **    vertex buffer objects in OpenGL.)
         **
         **    The position of vertices in a non-deformable, non-skinned mesh
         **    remain fixed from frame to frame.
         **
         **    Though they sound similar, skinned meshes and deformable meshes
         **    are different.  The vertices in a deformable mesh have already
         **    been transformed when the draw() function is called; nothing
         **    more needs to be done.  The vertices in a skinned mesh are not
         **    ready to be drawn, as they must first be transformed by a
         **    shader.
         **
         *b  Returns:
         **
         **    1 if mesh is deformable, 0 if not, -1 on failure
         */
        int get_is_deformable();

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


/*****************************************************************************/
/*********************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns a pointer to the shader program designated
         **    for this mesh, if any.  Shader programs are shared objects usable
         **    by many meshes.
         **
         *b  Returns:
         **
         **    pointer to diguyGraphicsShaderProgram, or NULL if this mesh
         **    does not have a shader specified
         */
        diguyGraphicsShaderProgram*  get_shader_program();

        /*l
         *b  Description:
         **
         **    If this mesh has a shader program specified (see
         **    get_shader_program()), this function returns a pointer to the
         **    shader instance object specific to this mesh.
         **
         *b  Returns:
         **
         **    pointer to diguyGraphicsShaderInstance, or NULL if this mesh
         **    does not have a shader specified
         */
        diguyGraphicsShaderInstance* get_shader_instance();


/*********************************************************************/
        /*l
         *b  Returns:
         **
         **    vertex format that describes the format of the data returned
         **    by the get_vertex_buffer_data() function
         */
        diguyGraphicsVertexFormat get_vertex_format();

        /*l
         *b  Returns:
         **
         **    how many vertices this mesh has
         */
        int get_vertex_count();

        /*l
         *b  Returns:
         **
         **    size, in bytes, of the data buffer returned by
         **    get_vertex_buffer_data()
         */
        int get_vertex_buffer_size();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the raw vertex buffer data
         **    of this mesh.  The format of the data can be obtained by calling
         **    get_vertex_format().
         **
         **    Type-correct pointers into the data can be obtained by calling
         **    get_first_vertex(), get_first_normal(), etc.
         **
         *b  Returns:
         **
         **    pointer to raw vertex buffer data
         */
        void* get_vertex_buffer_data();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to vertex position data of the
         **    first vertex in the raw vertex buffer data returned by
         **    get_vertex_buffer_data().
         **
         **    The XYZ position of the first vertex is stored in the first three
         **    values of the returned pointer.  The XYZ positions of subsequent
         **    vertices need to be obtained by consecutively adding the
         **    vertex stride to this returned pointer, as returned by
         **    get_vertex_stride().
         **
         **    *NOTE*: get_vertex_stride() returns a value in *bytes*, not
         **    sizeof(float), so be careful about pointer arithmetic.
         **
         **    This approach is also used for the first normal, texture indices,
         **    link index, and link weight of the vertex data.
         **
         **    An alternative approach to getting a pointer to the first vertex
         **    position is to use get_vertex_offset().  See that function for
         **    more information.
         **
         *b  Returns:
         **
         **    pointer to vertex position of first vertex in vertex buffer data
         */
        float* get_first_vertex();

        /*l
         *b  Description:
         **
         **    This function returns how many bytes the first vertex position
         **    is into the raw vertex buffer data returned by
         **    get_vertex_buffer_data().
         **
         **    The XYZ positions of subsequent vertices need to be obtained by
         **    consecutively adding the vertex stride to this offset, as
         **    returned by get_vertex_stride().
         **
         **    *NOTE*: get_vertex_stride() returns a value in *bytes*, not
         **    sizeof(float), so be careful about pointer arithmetic.
         **
         **    This approach is also used for the first normal, texture indices,
         **    link index, and link weight offsets into the vertex data.
         **
         **    An alternative approach to getting a pointer to the first vertex
         **    position is to use get_first_vertex() to get a type-correct
         **    pointer.
         **
         *b  Returns:
         **
         **    offset in bytes of the first vertex position in raw vertex buffer
         **    data
         */
        int get_vertex_offset();

        /*l
         *b  Description:
         **
         **    This function returns how many bytes there are between each
         **    vertex position in the raw data returned by
         **    get_vertex_buffer_data().
         **
         **    See get_first_vertex() and get_vertex_offset() for more
         **    information.
         **
         **    *NOTE*: this function returns a value in *bytes*, not
         **    sizeof(float), so be careful about pointer arithmetic.
         **
         *b  Returns:
         **
         **    stride in bytes between each vertex position in raw vertex buffer
         **    data
         */
        int get_vertex_stride();

        /*l
         *b  Returns:
         **
         **    pointer to normal of first vertex in vertex buffer data; see
         **    get_first_vertex() for more information
         */
        float* get_first_normal();

        /*l
         *b  Returns:
         **
         **    offset in bytes of the first normal in raw vertex buffer data;
         **    see get_vertex_offset() for more information
         */
        int get_normal_offset();

        /*l
         *b  Returns:
         **
         **    stride in bytes between each normal in raw vertex buffer
         **    data; see get_vertex_stride() for more information
         */
        int get_normal_stride();

        /*l
         *b  Returns:
         **
         **    pointer to texture indices of first vertex in vertex buffer data
         */
        float* get_first_texture_indices();

        /*l
         *b  Returns:
         **
         **    offset in bytes of the first texture indices in raw vertex buffer
         **    data; see get_vertex_offset() for more information
         */
        int get_texture_indices_offset();

        /*l
         *b  Returns:
         **
         **    stride in bytes between each texture indices pair in raw vertex
         **    buffer data; see get_vertex_stride() for more information
         */
        int get_texture_indices_stride();

        /*l
         *b  Returns:
         **
         **    pointer to link index of first vertex in vertex buffer data, in
         **    float form
         */
        float* get_first_link_index();

        /*l
         *b  Returns:
         **
         **    offset in bytes of the first link index in raw vertex buffer data;
         **    see get_vertex_offset() for more information
         */
        int get_link_index_offset();

        /*l
         *b  Returns:
         **
         **    stride in bytes between each link index in raw vertex buffer
         **    data; see get_vertex_stride() for more information
         */
        int get_link_index_stride();

        /*l
         *b  Returns:
         **
         **    pointer to link weight of first vertex in vertex buffer data
         */
        float* get_first_link_weight();

        /*l
         *b  Returns:
         **
         **    offset in bytes of the first link offset in raw vertex buffer data;
         **    see get_vertex_offset() for more information
         */
        int get_link_weight_offset();

        /*l
         *b  Returns:
         **
         **    stride in bytes between each link weight in raw vertex buffer data;
         **    see get_vertex_stride() for more information
         */
        int get_link_weight_stride();

        /*l
         *b  Description:
         **
         **    Returns a pointer to the UV tangent and flip bit of first vertex in
         **    the vertex buffer data.
         **
         **    There are 3 floats representing the tangent, and one for UV
         **    mirroring.  See
         **    http://www.dhpoware.com/demos/glslNormalMapping.html for an outline
         **    of how tangents are calculated.  Binormals are calculated in the
         **    vertex shader making their storage unnecessary.  Tangents should
         **    exist for all skinned/dae models.
         **
         **    See get_first_vertex() for more information about how to interpret
         **    tangent pointers and strides.
         */
        float* get_first_tangent();

        /*l
         *b  Returns:
         **
         **    offset in bytes of the first tangent in raw vertex buffer data;
         **    see get_vertex_offset() for more information
         */
        int get_tangent_offset();

        /*l
         *b  Returns:
         **
         **    stride in bytes between each tangent in raw vertex buffer data; see
         **    get_vertex_stride() for more information
         */
        int get_tangent_stride();

#endif


        /*********************************************************************/
        /*l
         *b  Returns:
         **
         **    index type used in data returned by the get_index_buffer_data()
         **    function
         */
        diguyGraphicsIndexType get_index_type();

        /*l
         *b  Description:
         **
         **    This function returns how many indices there are in this mesh.
         **    The number of triangles in this mesh can be derived by dividing
         **    this value by 3.
         **
         **    Note that indices in index buffer data are different than the
         **    indices contained in vertex buffer data.  Index buffer indices
         **    specify which *vertices* in vertex buffer data are used to create
         **    polygons in a mesh (e.g., for the first triangle, use vertices 0,
         **    1, and 2), while indices stored in vertex buffer data specify
         **    which *links* affect the final position of the vertex.
         **
         *b  Returns:
         **
         **    number of indices in index buffer data returned by
         **    get_index_buffer_data()
         */
        int get_index_count();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Returns:
         **
         **    size, in bytes, of the data buffer returned by
         **    get_index_buffer_data()
         */
        int get_index_buffer_size();

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the raw index buffer data of
         **    this mesh.  The format of the data can be obtained by calling
         **    get_index_type().
         **
         *b  Returns:
         **
         **    pointer to raw index buffer data
         */
        void* get_index_buffer_data();

#endif


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

        /*l
         *b  Description:
         **
         **    This function will be called by DI-Guy when it is time for a
         **    renderer-specific mesh object to be created.  All information
         **    necessary to build the mesh should be available via the
         **    Accessor Functions above when this function is called.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers may override this function, to
         **    create an object that may be invoked by draw().
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function, to
         **    create a geometry object that gets associated with a
         **    diguyGraphicsState object obtained by calling get_state().
         **
         *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 a
         **    renderer-specific mesh object to be destroyed.
         **
         *i  Immediate Mode:
         **
         **    Immediate mode renderers may override this function, to
         **    destroy any object that may have been created by build().
         **
         *i  Scene Graph:
         **
         **    Scene graph renderers usually do override this function, to
         **    destroy any object that may have been 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 the mesh should
         **    be drawn.  For scene graph renderers, most likely nothing
         **    more needs to be done by this function.
         **
         *b  Callable From:
         **
         *-    - N/A (automatically called by DI-Guy Graphics API during
         *-      Draw Stage)
         */
        virtual void draw();

#endif

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

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    Deprecated as of 10.0.0; use Geometry Data Accessor Functions
         **    instead.  This function can't provide data for all vertex formats
         **    or index formats that DI-Guy now supports.  This function assumes
         **    that vertex buffer data is in array format, and that indices in
         **    index buffer data are unsigned shorts.  Data for skinned meshes
         **    can't be represented with this function.
         */
        int get_vertex_info(int* num_vertices,
                float** vertex_array,
                float** normal_array,
                float** texture_array,
                int* index_array_size,
                unsigned short** index_array);

#endif


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

#ifdef CPLUSPLUS_ONLY

        diguyGraphicsMeshInternalData* get_internal_data() {return m_internal_data;}

protected:

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

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

private:

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

        friend class bdiGeometryGeosetMesh;
        friend class bdiGeometryGeoset;
        friend class bdiGeometryFactory;
        friend class diguyGraphicsMeshArray;
        friend class diguyGraphicsMeshInternalData;


#endif
};


#endif /* __diguyGraphicsMesh_H */