diguy_graphics_ogl.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.
 */

/*********************************************************************
 **
 *t  DI-Guy API, OpenGL Graphics Module
 **
 *b    Link against: libdiguy_graphics_ogl
 */

#ifndef __diguy_graphics_ogl_H
#define __diguy_graphics_ogl_H

#include <diguy_api.h>
#include <bdigraphics/graphics_init_ogl.h>

#include <declspec_diguy_graphics.h>

#ifdef __cplusplus
extern "C" {

class diguyScenario;
class diguyViewLight;
#endif


/*****************************************************************************
 **
 *2  Functions
 **
 */

/*l
 *b  Description:
 **
 **    This function initializes the DI-Guy Runtime API for the
 **    OpenGL environment.
 **
 *i    This function should only be called once per program execution.
 *i    Do not call this function again, even after calling
 *i    diguy_deinitialize().
 **
 **    Use diguy_ogl_get_defaults() to fill out the init structure before
 **    changing specific entries.
 **
 *b  Arguments:
 **
 *a    init - pointer to type bdiGraphicsInitOgl; passing NULL will cause
 *a           defaults to be used for all values
 **
 *b  Returns:
 **
 **    0 on success, non-zero error code on failure
 **
 **    Refer to diguy_constants.h for error code values.
 */
BDI_DECLSPEC_diguy_graphics int
diguy_ogl_initialize(bdiGraphicsInitOgl* init);

/*l
 *b  Description:
 **
 **    Fills out the init structure with default values.  Selected entries can
 **    then be changed before calling diguy_ogl_initialize().
 **
 *b  Arguments:
 **
 *a    init - pointer to type bdiGraphicsInitOgl
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 */
BDI_DECLSPEC_diguy_graphics int
diguy_ogl_get_defaults(bdiGraphicsInitOgl* init);


/*l
 *   Documentation Pending.
 **
 *b  Description:
 **
 **    This function is the default fire intersection function.  It uses a
 **    minimal render of the scene and characters into the back buffer to fill
 **    out the impact structure.
 **
 **    It may be useful to combine your intersection results with the results
 **    from this function.
 */
BDI_DECLSPEC_diguy_graphics
int diguy_default_fire_weapon_intersection_function(diguyImpact* impact,
        float from_x,
        float from_y,
        float from_z,
        float to_x,
        float to_y,
        float to_z,
        diguyScenario* scenario);


/****************************************************************************/
/****************************************************************************/
/*****************************************************************************
 **
 *2  Experimental Functions
 **
 **  The following functions are experimental and may change or
 **   disappear with no warning.
 */
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

#ifdef CPLUSPLUS_ONLY

/*l
 *b  Description:
 **
 **    This function queries the character for the OpenGL texture
 **    objects it is using and stores them in an internal list.  This
 **    internal list can then be accessed via the following functions:
 **
 *e     diguy_ogl_get_character_texture_list_num_textures();
 *e     diguy_ogl_get_character_texture_list_texture_object_at_index();
 *e     diguy_ogl_get_character_texture_list_texture_filename_at_index();
 **
 **    The function diguy_ogl_release_character_texture_list() should
 **    be called once query calls are complete to avoid a resource leak.
 **
 **    Note that there is currently only one internal texture list; there
 **    are not separate lists per character.  Calling this function again,
 **    even with a different scenario pointer and/or character index, will
 **    clobber the previous texture list.
 **
 *b  Arguments:
 **
 *a    scenario             - pointer to character's scenario
 *a    character_index      - index of character to be queried
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 *b  C++ Example:
 **
 *e     diguy_ogl_generate_character_texture_list(scenario,
 *e             character_index);
 *e     
 *e     int texture_count = diguy_ogl_get_character_texture_list_num_textures(scenario,
 *e             character_index);
 *e     
 *e     if (texture_count > 0)
 *e     {
 *e             int texture_index;
 *e     
 *e             for (texture_index = 0;
 *e                     texture_index < texture_count;
 *e                     texture_index++)
 *e             {
 *e                     GLuint texture_object = diguy_ogl_get_character_texture_list_texture_object_at_index(scenario,
 *e                             character_index,
 *e                             texture_index);
 *e     
 *e                     const char* texture_filename = diguy_ogl_get_character_texture_list_texture_filename_at_index(scenario,
 *e                             character_index,
 *e                             texture_index);
 *e     
 *e                     bdi_log_printf(BDI_LOG_WARN, "\ttexture object = %ld, filename = %s\n",
 *e                             texture_object,
 *e                             texture_filename);
 *e             }
 *e     
 *e             GLuint texture_object = diguy_ogl_get_character_texture_list_texture_object_at_index(scenario,
 *e                     character_index,
 *e                     0); // the first texture in the list
 *e     
 *e             //
 *e             //  (Code to override/replace the texture)
 *e             //
 *e     
 *e             diguy_ogl_set_character_texture_objects_modified(scenario,
 *e                     character_index);
 *e     
 *e             diguy_ogl_release_character_texture_list(scenario,
 *e                     character_index);
 *e     }
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_generate_character_texture_list(diguyScenario* scenario,
        int character_index);

/*l
 *b  Description:
 **
 **    This function releases a texture list generated by
 **    diguy_ogl_generate_character_texture_list().
 **
 *b  Arguments:
 **
 *a    scenario             - pointer to character's scenario
 *a    character_index      - index of character to be queried
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_release_character_texture_list(diguyScenario* scenario,
        int character_index);

/*l
 *b  Description:
 **
 **    This function returns the number of textures used by the specified
 **    character.
 **
 **    The function diguy_ogl_generate_character_texture_list() must be
 **    called before this function.  The scenario and character_index
 **    arguments passed to this function must match those passed to the
 **    generate function.
 **
 *b  Arguments:
 **
 *a    scenario             - pointer to character's scenario
 *a    character_index      - index of character to be queried
 **
 *b  Returns:
 **
 **    number of textures in texture list
 **
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_get_character_texture_list_num_textures(diguyScenario* scenario,
        int character_index);

/*l
 *b  Description:
 **
 **    This function returns the OpenGL texture object at the specified
 **    index.
 **
 **    The function diguy_ogl_generate_character_texture_list() must be
 **    called before this function.  The scenario and character_index
 **    arguments passed to this function must match those passed to the
 **    generate function.
 **
 *b  Arguments:
 **
 *a    scenario             - pointer to character's scenario
 *a    character_index      - index of character to be queried
 *a    texture_list_index   - index of texture in texture list
 **
 *b  Returns:
 **
 **    OpenGL texture object
 **
 */
BDI_DECLSPEC_diguy_graphics
GLuint diguy_ogl_get_character_texture_list_texture_object_at_index(diguyScenario* scenario,
        int character_index,
        int texture_list_index);

/*l
 *b  Description:
 **
 **    This function returns the filename of the texture at the specified
 **    index.
 **
 **    The function diguy_ogl_generate_character_texture_list() must be
 **    called before this function.  The scenario and character_index
 **    arguments passed to this function must match those passed to the
 **    generate function.
 **
 *b  Arguments:
 **
 *a    scenario             - pointer to character's scenario
 *a    character_index      - index of character to be queried
 *a    texture_list_index   - index of texture in texture list
 **
 *b  Returns:
 **
 **    filename of the texture
 **
 */
BDI_DECLSPEC_diguy_graphics
const char* diguy_ogl_get_character_texture_list_texture_filename_at_index(diguyScenario* scenario,
        int character_index,
        int texture_list_index);

/*l
 *b  Description:
 **
 **    This function notifies the character that its texture objects have
 **    been modified and that it should take any steps necessary to update
 **    its internal state to ensure proper display.
 **
 *b  Arguments:
 **
 *a    scenario             - pointer to character's scenario
 *a    character_index      - index of character to be queried
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_set_character_texture_objects_modified(diguyScenario* scenario,
        int character_index);

/*l
 *b  Description:
 **
 **    This function returns the texture unit that DI-Guy is currently set to
 **    use.
 **
 *b  Returns:
 **
 **    integer identifying texture unit; e.g., 0 for texture unit 0
 **
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_get_texture_unit();

/*l
 *b  Description:
 **
 **    This function sets the texture unit that DI-Guy should use.
 **
 *b  Arguments:
 **
 *a    texture_unit - integer identifying texture unit
 **
 **    Possible values are:
 **
 *a    0 - use GL_TEXTURE0
 *a    1 - use GL_TEXTURE1
 *a    2 - use GL_TEXTURE2
 *a    3 - use GL_TEXTURE3
 **
 *b  Returns:
 **
 **    0 on success, -1 on failure
 **
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_set_texture_unit(int texture_unit);

/*l
 *b  Description:
 **
 **    This function turns far position rendering on or off.  See
 **    diguyViewCamera for more information on far positions.
 **
 *b  Arguments:
 **
 *a    val - pass 1 to use far positions, 0 to not use them
 **
 */
BDI_DECLSPEC_diguy_graphics
void diguy_ogl_set_use_far_positions(int val);

/*l
 *b  Returns:
 **
 **    1 if far positions are in use, else 0
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_get_use_far_positions();

/*l
 *b  Description:
 **
 **    This function sets the shader source files that will be used for the
 **    specified shader.
 **
 **    The default filenames for the "diguy_character" shader are
 **    "diguy_character_glsl.vert" and "diguy_character_glsl.frag".
 **
 *b  Arguments:
 **
 *a    shader_name    - name with which vertex/pixel shader pair can be
 *a                     referenced
 *a    vert_filename  - name of vertex shader source file
 *a    pixel_filename - name of pixel (fragment) shader source file
 **
 */
BDI_DECLSPEC_diguy_graphics
void diguy_ogl_set_default_shader_source_files(const char* shader_name,
        const char* vert_filename,
        const char* pixel_filename);

/*l
 *b  Description:
 **
 **    Renders a shadow pass of the world and binds into the target texture unit.
 **/
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_render_shadow_map(unsigned int texture_unit,  // 0 to 7, not GL_TEXTURE0 to GL_TEXTURE7
        diguyViewLight* light,
        diguyScenario* scenario,
        float pos_above_terrain);

/*l
 *b  Description:
 **
 **   Applies active lights to the OpenGL state, also updates default shader uniforms 
 **   and calls diguyScenario::set_num_active_point_lights()
 **   
 *b  Returns:
 **   
 **     The number of active lights 
 **/
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_apply_active_lights(diguyScenario* scenario);

/****************************************************************************/
/****************************************************************************/
/*****************************************************************************
 **
 *2  Experimental Heads-Up Display Functions
 **
 **  The following functions are experimental and may change or
 **   disappear with no warning.
 */
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_2d_set_color(float r, float g, float b, float a);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_2d_draw_filled_rect(int x0, int y0, int x1, int y1);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_2d_draw_text(int x, int y, const char* text);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_2d_get_text_width(const char* text);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_2d_get_text_height(const char* text);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_get_fbo_texture_id();

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_reload_changed_textures();


/*****************************************************************************
 **
 *2  Experimental frame stats API
 **
 **    Currently available stats:
 *>
 *-    - "characters_drawn"
 *-    - "links_drawn"
 *-    - "shapes_drawn"
 *-    - "nodes_drawn"
 *-    - "mats_bound"
 *-    - "groups_drawn"
 *-    - "textures_bound"
 *-    - "vbos_drawn"
 *-    - "rigid_vbos_drawn",
 *-    - "skinned_vbos_drawn"
 *-    - "tris_drawn"
 *-    - "verts_drawn"
 *<
 **     Stats should be cleared once a frame to get accurate results.
 */
BDI_DECLSPEC_diguy_graphics
int diguy_ogl_get_num_frame_stats();

BDI_DECLSPEC_diguy_graphics
const char* diguy_ogl_frame_stat_name(int index);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_get_frame_stat(const char* stat_name);

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_clear_all_frame_stats();

BDI_DECLSPEC_diguy_graphics
int diguy_ogl_draw_frame_stats(int sx, int sy);

#endif // CPLUSPLUS_ONLY

#ifdef __cplusplus
}
#endif


#endif /* __diguy_graphics_ogl_H */


/*
 *  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.
 */