diguyAuthorInterface

Generated from diguyAuthorInterface.h

DI-Guy API Version 12.5.1

This file was automatically generated from diguyAuthorInterface.h. Do not edit this file directly; the changes will be lost.

Includes: stdio.h | declspec_diguy.h | diguy_constants.h | diguy_vector_classes.h

Contents:

Alphabetical Index

constants

#define AUTHOR_UI_MAIN_WINDOW_NAME         "main_window"
#define AUTHOR_UI_INPUT_MODE_WINDOW_NAME   "input_mode"
#define AUTHOR_UI_TIME_CONTROL_WINDOW_NAME "time_control"
#define AUTHOR_UI_LOG_WINDOW_NAME          "log"
#define AUTHOR_UI_VISIBILITY_WINDOW_NAME   "visibility"
#define AUTHOR_UI_ELEMENTS_WINDOW_NAME     "elements"
#define AUTHOR_UI_CHARACTER_WINDOW_NAME    "character"
#define AUTHOR_UI_CROWD_WINDOW_NAME        "crowd"
#define AUTHOR_UI_MIND_EDITOR_WINDOW_NAME  "mind_editor"
#define AUTHOR_UI_AI_INSPECTOR_WINOW_NAME  "ai_inspector"

Link against: libdiguy

Summary:

The diguyAuthorInterface class provides an interface for sending input to DI-Guy Author from a DI-Guy Author enabled IG, receiving commands from DI-Guy Author, and querying for other DI-Guy data.

class diguyAuthorInterface

class BDI_DECLSPEC_diguy diguyAuthorInterface
{
public:
    diguyAuthorVisualRegionPaintbrush* get_region_paintbrush();
    void set_mouse_screen_coordinates(int x, int y);
    void set_mouse_world_coordinates(diguyVec3f world_coords);
    void set_mouse_button_l(int button_state);
    void set_mouse_button_r(int button_state);
    void set_mouse_button_m(int button_state);
    void set_mouse_wheel_change(float mouse_wheel_change);
    void apply_mouse_inputs();
    void set_keyboard_shift(int key_state);
    void set_keyboard_ctrl(int key_state);
    void set_keyboard_alt(int key_state);
    void set_key_pressed(int key, int key_state);
    int set_selected_diguy_uid(long uid);
    int set_selected_diguy_uid_from_string(const char* uid_string);
    int get_uid_base_type(long uid);
    int get_uid_base_type_from_string(const char* uid_string);
    diguyCharacter* get_selected_character();
    diguyCharacterPath* get_selected_character_path();
    diguyWaypoint* get_selected_waypoint();
    diguyPathShape* get_selected_path_shape();
    diguyGraphicsLink* get_selected_link();
    diguyGraphicsShape* get_selected_shape();
    virtual int convert_screen_to_world(const diguyVec3f& screen_xyz,
        diguyVec3f* world_xyz) = 0;
    virtual int convert_world_to_screen(const diguyVec3f& world_xyz,
        diguyVec3f* screen_xyz) = 0;
    virtual float get_altitude(float x, float y, float old_z,
        float from_height = 10.0f,
        int* valid_result = NULL) = 0;
    virtual int update_selected_objects(const diguyVec3f& screen_xyz) = 0;
    virtual int check_z_clearance(const diguyVec3f& pos,
        const float radius,
        const float ground_angle,
        float z_clear_height,
        int check_below = 1) const = 0;
    int set_author_ui_window_visible(const char* window_name, int visible);
    int get_author_ui_window_visible(const char* window_name);
    int set_author_ui_panel_visible(const char* panel_name);
    int set_author_ui_select_crowd_character(diguyCharacter* character);
    int set_author_ui_select_code_browser_script(diguyCharacter* character);
#ifdef CPLUSPLUS_ONLY
    virtual void author_ui_window_visibility_changed(const char* window_name,
        int is_visible);
#endif
#ifdef CPLUSPLUS_ONLY
    static int generate_sphere_vertices(float radius,
        int num_slices,
        int num_layers,
        const diguyVec3f& position_offset,
        const diguyVec3f& orientation,      // degrees
        int* num_vertices,
        diguyVec3f** vertices,
        diguyVec3f** normals,
        diguyVec2f** texture_indices,
        int indices_for_wireframe,
        int* num_indices,
        unsigned int** indices);
    static int generate_cone_vertices(float radius,
        float height,
        int num_slices,
        int num_layers,
        const diguyVec3f& position_offset,
        const diguyVec3f& orientation,      // degrees
        int* num_vertices,
        diguyVec3f** vertices,
        diguyVec3f** normals,
        diguyVec2f** texture_indices,
        int indices_for_wireframe,
        int* num_indices,
        unsigned int** indices);
    static int generate_cylinder_vertices(float radius,
        float height,
        int num_slices,
        int num_layers,
        const diguyVec3f& position_offset,
        const diguyVec3f& orientation,      // degrees
        int* num_vertices,
        diguyVec3f** vertices,
        diguyVec3f** normals,
        diguyVec2f** texture_indices,
        int indices_for_wireframe,
        int* num_indices,
        unsigned int** indices);
    static int generate_box_vertices(diguyVec3f min,
        diguyVec3f max,
        const diguyVec3f& position_offset,
        const diguyVec3f& orientation,      // degrees
        int* num_vertices,
        diguyVec3f** vertices,
        diguyVec3f** normals,
        diguyVec2f** texture_indices,
        int indices_for_wireframe,
        int* num_indices,
        unsigned int** indices);
    static void delete_generated_vertices(diguyVec3f* vertices,
        diguyVec3f* normals,
        diguyVec2f* texture_indices,
        unsigned int* indices);
#endif

function diguyAuthorInterface::get_region_paintbrush

Prototype:
diguyAuthorVisualRegionPaintbrush* get_region_paintbrush();
Returns a pointer to the region paintbrush. Returned pointer may be NULL.

Mouse Functions

In most DI-Guy Author input modes the position of the mouse and state of the mouse buttons are very important. These functions allow the Host IG to tell DI-Guy Author the state of the mouse. They should be called from the Host IG when mouse events occur.

These functions should not be called when DI-Guy Author is inactive. DI-Guy Author is inactive when diguyApp::get_base_input_mode() returns DIGUY_SCENARIO_INPUT_MODE_NONE.

function diguyAuthorInterface::set_mouse_screen_coordinates

Prototype:
void set_mouse_screen_coordinates(int x, int y);
Description:

Sets the current position of the mouse in screen coordinates.

This should be done whenever a DI-Guy input mode is active and the mouse moves.

Note that nothing is done with this information until apply_mouse_inputs() is called.
Arguments:

x horizontal pixel from left edge of window
y vertical pixel from bottom edge of window

function diguyAuthorInterface::set_mouse_world_coordinates

Prototype:
void set_mouse_world_coordinates(diguyVec3f world_coords);
Description:

Sets the current position of the mouse in world coordinates. This should be the intersection point of the ray that would begin at the mouse's screen position, and extend into the far distance (at least as far as the graphics far plane).

This should be done whenever a DI-Guy input mode is active, and a point in the 3D world is requested, such as during a call to convert_screen_to_world().

Note that nothing is done with this information until apply_mouse_inputs() is called.
Arguments:

world_coords mouse position in world coordinates, in meters from the origin

function diguyAuthorInterface::set_mouse_button_l

Prototype:
void set_mouse_button_l(int button_state);
Description:

Sets the current state of the left mouse button.

This should be done whenever a DI-Guy input mode is active and the a mouse button is pressed.

Note that nothing is done with this information until apply_mouse_inputs() is called.
Arguments:

button_state 1 for down, 0 for up

function diguyAuthorInterface::set_mouse_button_r

Prototype:
void set_mouse_button_r(int button_state);
Description:

Same as set_mouse_button_l(), but for the right mouse button.

function diguyAuthorInterface::set_mouse_button_m

Prototype:
void set_mouse_button_m(int button_state);
Description:

Same as set_mouse_button_m(), but for the middle mouse button.

function diguyAuthorInterface::set_mouse_wheel_change

Prototype:
void set_mouse_wheel_change(float mouse_wheel_change);
Description:

Sets the change in the mouse wheel position since the last call to this function.

This should be done whenever a DI-Guy input mode is active and the the mouse wheel is moved.

Note that nothing is done with this information until apply_mouse_inputs() is called.
Arguments:

mouse_wheel_change (units documentation pending)

function diguyAuthorInterface::apply_mouse_inputs

Prototype:
void apply_mouse_inputs();
Description:

Applies effects of inputs set by set_mouse_screen_coordinates(), set_mouse_button_l(), etc. DI-Guy Author will make modifications on edited objects based on these inputs.

Keyboard Functions

In most DI-Guy Author input modes the state of various keys can change the behavior of the input mode. These functions allow the Host IG to tell DI-Guy Author the state of the keyboard.

Keyboard inputs aren't nearly important to DI-Guy Author as mouse events are, and it's easily possible for the Host IG to not want to pass key events to DI-Guy Author as the Host IG wants to handle them itself.

These functions should not be called when DI-Guy Author is inactive. DI-Guy Author is inactive when diguyApp::get_base_input_mode() returns DIGUY_SCENARIO_INPUT_MODE_NONE.

function diguyAuthorInterface::set_keyboard_shift

Prototype:
void set_keyboard_shift(int key_state);
Description:

Sets the current state of the shift key. The shift key can change the results of mouse inputs in the 3D window.

This should be done whenever a DI-Guy input mode is active and the state of the shift key changes.
Arguments:

key_state 1 for down, 0 for up

function diguyAuthorInterface::set_keyboard_ctrl

Prototype:
void set_keyboard_ctrl(int key_state);
Description:

Same as set_keyboard_shift(), but for ctrl key.

function diguyAuthorInterface::set_keyboard_alt

Prototype:
void set_keyboard_alt(int key_state);
Description:

Same as set_keyboard_alt(), but for alt key.

function diguyAuthorInterface::set_key_pressed

Prototype:
void set_key_pressed(int key, int key_state);
Description:

Sets the current state of the speficied key. Key presses can change the input mode, cause a reset, load camera settings, etc.

Note: Often it will be better for the Host IG to handle key presses and make the appropriate DI-Guy calls manually.
Arguments:

key ASCII code of pressed key
key_state 1 for down, 0 for up

Selected Object Functions

Most DI-Guy objects have a unique identifier (uid): a numerical value that can be used to identify the object. In DI-Guy Author they are useful for setting the names or other identifiers of objects in the 3D scene, so that if those objects are clicked on it can be determined whether the clicked point is on a DI-Guy object, and if so which one.

Different DI-Guy objects have uids in different ranges. The object type can be derived from the uid by calling get_uid_base_type().

function diguyAuthorInterface::set_selected_diguy_uid

Prototype:
int set_selected_diguy_uid(long uid);
Description:

Sets the current selected DI-Guy object based on the passed uid. If the uid matches an object in the scenario, that object will become the selected object.

This function is typically called during a update_selected_objects() call.

The type of object the uid is associated with can be determined by calling get_uid_base_type().

DI-Guy Author will internally decide what the uid code means, and set its selected object pointers appropriately. The get_selected_* functions below (e.g., get_selected_character()) will return objects that are selected as a result of this call. Calling this function will un-select all other objects, even if they are of different types.

Note, however, that in some cases multiple objects may become selected, if the uid of the object is for an object owned by another. For example, selecting a waypoint will also select the waypoint's path, and the path's character.
Arguments:

uid unique identifier of selected object
Returns:

1 if uid is valid, 0 if not (e.g., no such object)

function diguyAuthorInterface::set_selected_diguy_uid_from_string

Prototype:
int set_selected_diguy_uid_from_string(const char* uid_string);
Description:

Same as set_selected_diguy_uid(), but with uid in string form.

function diguyAuthorInterface::get_uid_base_type

Prototype:
int get_uid_base_type(long uid);
Description:

Returns a value that describes the object type associated with the passed uid. The returned value will be one of the DIGUY_TYPE_UID_BASE_* values listed in diguy_constants.h; e.g., a return value of DIGUY_TYPE_UID_BASE_CHARACTER means that the uid is associated with a diguyCharacter object.

DIGUY_TYPE_UID_BASE_NOTHING is returned if the passed value is not a valid DI-Guy uid.
Arguments:

uid unique identifier to be checked
Returns:

uid base type enumeration

function diguyAuthorInterface::get_uid_base_type_from_string

Prototype:
int get_uid_base_type_from_string(const char* uid_string);
Description:

Same as get_uid_base_type(), but with uid in string form.

function diguyAuthorInterface::get_selected_character

Prototype:
diguyCharacter* get_selected_character();
Description:

Returns the character that was selected as a result of calling set_selected_diguy_uid().
Returns:

pointer to type diguyCharacter

function diguyAuthorInterface::get_selected_character_path

Prototype:
diguyCharacterPath* get_selected_character_path();
Description:

diguyCharacterPath version of get_selected_character().

function diguyAuthorInterface::get_selected_waypoint

Prototype:
diguyWaypoint* get_selected_waypoint();
Description:

diguyWaypoint version of get_selected_character().

function diguyAuthorInterface::get_selected_path_shape

Prototype:
diguyPathShape* get_selected_path_shape();
Description:

diguyPathShape version of get_selected_character().

function diguyAuthorInterface::get_selected_link

Prototype:
diguyGraphicsLink* get_selected_link();
Description:

diguyGraphicsLink version of get_selected_character().

function diguyAuthorInterface::get_selected_shape

Prototype:
diguyGraphicsShape* get_selected_shape();
Description:

diguyGraphicsShape version of get_selected_character().

Terrain and Intersection Virtual Functions

The functions in this section are used by DI-Guy Author to query for information from the world. They are virual functions that should be overridden in the Host IG to provide the requested information.

World coordinates are in DI-Guy's standard coordinate system that has Z up.

Screen coordinates (also sometimes referred to as window coordinates) are in pixels, where:

x is the horizontal pixel from left side of window
y is the vertical pixel from bottom of window
z is the depth of pixel in the Z buffer: 0 at near plane, 1 at far plane

function diguyAuthorInterface::convert_screen_to_world

Prototype:
virtual int convert_screen_to_world(const diguyVec3f& screen_xyz,
    diguyVec3f* world_xyz) = 0;
Description:

This function will be called when DI-Guy Author nneds to know the world position behind the given screen coordinate.

See above for information on the world and screen coordinate systems.

A typical implementation will construct a ray with its beginning at the world coordinate corresponding to the screen coordinate, projected some distance into the world using a camera projection matrix.
Arguments:

screen_xyz screen coordinates as described above
world_xyz return value world intersection point
Returns:

1 if an intersection occurred, 0 if not

function diguyAuthorInterface::convert_world_to_screen

Prototype:
virtual int convert_world_to_screen(const diguyVec3f& world_xyz,
    diguyVec3f* screen_xyz) = 0;
Description:

This function is the inverse of convert_screen_to_world(). It takes a world position and returns the corresponding screen coordinate.
Arguments:

world_xyz point in world coordinates
screen_xyz return value screen coordinate that covers that point
Returns:

1 if an intersection occurred, 0 if not

function diguyAuthorInterface::get_altitude

Prototype:

virtual float get_altitude(float x, float y, float old_z,
    float from_height = 10.0f,
    int* valid_result = NULL) = 0;

function diguyAuthorInterface::update_selected_objects

Prototype:

virtual int update_selected_objects(const diguyVec3f& screen_xyz) = 0;

function diguyAuthorInterface::check_z_clearance

Prototype:

virtual int check_z_clearance(const diguyVec3f& pos,
    const float radius,
    const float ground_angle,
    float z_clear_height,
    int check_below = 1) const = 0;

Author UI Functions

The functions in this section are for interactions with the 2D user interface side of DI-Guy Author, as implemented in the application DIGuyAuthorUI. These functions can be called from the Host IG.

Because the Author UI is in a separate process there are a number of communication details that these functions will help with.

function diguyAuthorInterface::set_author_ui_window_visible

Prototype:
int set_author_ui_window_visible(const char* window_name, int visible);
Description:

Calling this function will tell the DI-Guy Author UI to show or hide the specified window.
Arguments:

window_name name of the window to show or hide
visible pass 1 to show the window, 0 to hide it

Currently valid window names are:

"input_mode"
"time_control"
"log"
"elements"

function diguyAuthorInterface::get_author_ui_window_visible

Prototype:
int get_author_ui_window_visible(const char* window_name);
Returns:

1 if the specified DI-Guy Author UI window is shown, 0 if not
Arguments:

window_name name of the window to show or hide

function diguyAuthorInterface::set_author_ui_panel_visible

Prototype:
int set_author_ui_panel_visible(const char* panel_name);
Description:

Calling this function will tell the DI-Guy Author UI to show the specified panel in the elements window.
Arguments:

panel_name name of the window to show or hide

Currently valid window names are:

"Character"
"Crowd"

function diguyAuthorInterface::set_author_ui_select_crowd_character

Prototype:
int set_author_ui_select_crowd_character(diguyCharacter* character);
Description:

Calling this function will tell the DI-Guy Author UI to select the specified character in the crowd page.
Arguments:

character name of the character to select in the crowd window

function diguyAuthorInterface::set_author_ui_select_code_browser_script

Prototype:
int set_author_ui_select_code_browser_script(diguyCharacter* character);
Description:

Calling this function will tell the DI-Guy Author UI to select the specified script for the character.
Arguments:

character name of the character to select in the crowd window

Author UI Status Update Functions

The functions in this section will be called by DI-Guy Author when the status of various parts of the DI-Guy Author UI application change. They are virtual functions that the Host IG should override. This gives the Host IG a chance to update its state on what is happening with the Author UI, such as enabling or disabling various native user interface controls.

function diguyAuthorInterface::author_ui_window_visibility_changed

Prototype:
virtual void author_ui_window_visibility_changed(const char* window_name,
    int is_visible);
Description:

Called if the named window in the Author UI application changes visibility state.

Utility Vertex Generation Functions

The functions in this section are utility functions for generating vertices that can be used for rending 3D DI-Guy Author visuals in the Host IG. These functions will typically be called from diguyAuthorVisual subclasses.

For example, in DI-Guy Scenario and the DI-Guy Author Host IG reference implementation, path waypoints are shown as line segments with side wings and a vertical post, and a cone at the end of the forward facing segment representing an arrowhead. The subclass that creates the Host IG native 3D visuals can call these functions to get the recommended vertex information with which native 3D objects can be constructed. In the case of the diguyAuthorVisualWaypoint subclass, multiple calls to generate_box_vertices() can be made to generate vertices for the various posts, and one call to generate_cone_vertices() can be made to generate the vertices for the arrowhead.

The DI-Guy Author Host IG reference implementation that is based on Open Scene Graph provides very clear examples of how these functions can be used.

Returned pointers must be deleted by calling delete_generated_vertices().

Vertices are returned in diguyGraphicsVertexFormat DIGUY_GRAPHICS_VERTEX_FORMAT_V3_N3_T2.

function diguyAuthorInterface::generate_sphere_vertices

Prototype:
static int generate_sphere_vertices(float radius,
    int num_slices,
    int num_layers,
    const diguyVec3f& position_offset,
    const diguyVec3f& orientation,      // degrees
    int* num_vertices,
    diguyVec3f** vertices,
    diguyVec3f** normals,
    diguyVec2f** texture_indices,
    int indices_for_wireframe,
    int* num_indices,
    unsigned int** indices);
Description:

Generates vertices for a sphere with the passed radius. The data returned in the vertices, normals, texture_indices, and indices pointers must be deleted using delete_generated_vertices().

Untransformed, the sphere's center will be at the local origin.

The slices will radiate around the z axis. The stacks will be along the z axis.
Arguments:

radius (input) radius of sphere, in meters
num_slices (input) number of radial slices; think slices in a cake
num_layers (input) number of vertical layers; think layers in a cake
position_offset (input) position offset of sphere from local origin, in meters
orientation (input) orientation offset of sphere about local origin, in degrees
num_vertices (output) number of generated vertices
vertices (output) vertex data
normals (output) normal data
texture_indices (output) texture index data (not currently used)
indices_for_wireframe (input) pass 1 if vertices are for a wireframe object that will be represented be line segments, 0 if the vertices are for a solid object represented by polygons
num_indices (output) number of indices telling how vertices connect
indices (output) data on how vertices connect
Returns:

0 on success, -1 on error

function diguyAuthorInterface::generate_cone_vertices

Prototype:
static int generate_cone_vertices(float radius,
    float height,
    int num_slices,
    int num_layers,
    const diguyVec3f& position_offset,
    const diguyVec3f& orientation,      // degrees
    int* num_vertices,
    diguyVec3f** vertices,
    diguyVec3f** normals,
    diguyVec2f** texture_indices,
    int indices_for_wireframe,
    int* num_indices,
    unsigned int** indices);
Description:

Similar to generate_sphere_vertices(), but for cones.

Untransformed, the cone's base will be at the local origin, with the point tapering in positive z.

The slices will radiate around the z axis. The stacks will be along the z axis.

function diguyAuthorInterface::generate_cylinder_vertices

Prototype:
static int generate_cylinder_vertices(float radius,
    float height,
    int num_slices,
    int num_layers,
    const diguyVec3f& position_offset,
    const diguyVec3f& orientation,      // degrees
    int* num_vertices,
    diguyVec3f** vertices,
    diguyVec3f** normals,
    diguyVec2f** texture_indices,
    int indices_for_wireframe,
    int* num_indices,
    unsigned int** indices);
Description:

Similar to generate_sphere_vertices(), but for cylinders.

Untransformed, the cylinder's base will be at the local origin, the top above the base in positive z.

The slices will radiate around the z axis. The stacks will be along the z axis.

function diguyAuthorInterface::generate_box_vertices

Prototype:
static int generate_box_vertices(diguyVec3f min,
    diguyVec3f max,
    const diguyVec3f& position_offset,
    const diguyVec3f& orientation,      // degrees
    int* num_vertices,
    diguyVec3f** vertices,
    diguyVec3f** normals,
    diguyVec2f** texture_indices,
    int indices_for_wireframe,
    int* num_indices,
    unsigned int** indices);
Description:

Similar to generate_sphere_vertices(), but for boxes, AKA rectangular solids.

Untransformed, the box's corners are represented by the passed min and max vectors, relative to the local origin.

function diguyAuthorInterface::delete_generated_vertices

Prototype:
static void delete_generated_vertices(diguyVec3f* vertices,
    diguyVec3f* normals,
    diguyVec2f* texture_indices,
    unsigned int* indices);
Description:

For deleting data generated by the various generate_*_vertices() functions.

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.

`x`	horizontal pixel from left edge of window
`y`	vertical pixel from bottom edge of window

`key`	ASCII code of pressed key
`key_state`	1 for down, 0 for up

`screen_xyz`	screen coordinates as described above
`world_xyz`	return value world intersection point

`world_xyz`	point in world coordinates
`screen_xyz`	return value screen coordinate that covers that point

`window_name`	name of the window to show or hide
`visible`	pass 1 to show the window, 0 to hide it

`radius`	(input) radius of sphere, in meters
`num_slices`	(input) number of radial slices; think slices in a cake
`num_layers`	(input) number of vertical layers; think layers in a cake
`position_offset`	(input) position offset of sphere from local origin, in meters
`orientation`	(input) orientation offset of sphere about local origin, in degrees
`num_vertices`	(output) number of generated vertices
`vertices`	(output) vertex data
`normals`	(output) normal data
`texture_indices`	(output) texture index data (not currently used)
`indices_for_wireframe`	(input) pass 1 if vertices are for a wireframe object that will be represented be line segments, 0 if the vertices are for a solid object represented by polygons
`num_indices`	(output) number of indices telling how vertices connect
`indices`	(output) data on how vertices connect