Link against: libdiguy More...

#include <diguyAuthorInterface.h>

Public Member Functions
diguyAuthorVisualRegionPaintbrush *	get_region_paintbrush ()
	Returns a pointer to the region paintbrush. More...

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.
void	set_mouse_screen_coordinates (int x, int y)
	Sets the current position of the mouse in screen coordinates. More...

void	set_mouse_world_coordinates (diguyVec3f world_coords)
	Sets the current position of the mouse in world coordinates. More...

void	set_mouse_button_l (int button_state)
	Sets the current state of the left mouse button. More...

void	set_mouse_button_r (int button_state)
	Same as set_mouse_button_l(), but for the right mouse button. More...

void	set_mouse_button_m (int button_state)
	Same as set_mouse_button_m(), but for the middle mouse button. More...

void	set_mouse_wheel_change (float mouse_wheel_change)
	Sets the change in the mouse wheel position since the last call to this function. More...

void	apply_mouse_inputs ()
	Applies effects of inputs set by set_mouse_screen_coordinates(), set_mouse_button_l(), etc. More...

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.
void	set_keyboard_shift (int key_state)
	Sets the current state of the shift key. More...

void	set_keyboard_ctrl (int key_state)
	Same as set_keyboard_shift(), but for ctrl key. More...

void	set_keyboard_alt (int key_state)
	Same as set_keyboard_alt(), but for alt key. More...

void	set_key_pressed (int key, int key_state)
	Sets the current state of the speficied key. More...

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().
int	set_selected_diguy_uid (long uid)
	Sets the current selected DI-Guy object based on the passed uid. More...

int	set_selected_diguy_uid_from_string (const char *uid_string)
	Same as set_selected_diguy_uid(), but with uid in string form. More...

int	get_uid_base_type (long uid)
	Returns a value that describes the object type associated with the passed uid. More...

int	get_uid_base_type_from_string (const char *uid_string)
	Same as get_uid_base_type(), but with uid in string form. More...

diguyCharacter *	get_selected_character ()
	Returns the character that was selected as a result of calling set_selected_diguy_uid(). More...

diguyCharacterPath *	get_selected_character_path ()
	diguyCharacterPath version of get_selected_character(). More...

diguyWaypoint *	get_selected_waypoint ()
	diguyWaypoint version of get_selected_character(). More...

diguyPathShape *	get_selected_path_shape ()
	diguyPathShape version of get_selected_character(). More...

diguyGraphicsLink *	get_selected_link ()
	diguyGraphicsLink version of get_selected_character(). More...

diguyGraphicsShape *	get_selected_shape ()
	diguyGraphicsShape version of get_selected_character(). More...

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
virtual int	convert_screen_to_world (const diguyVec3f &screen_xyz, diguyVec3f *world_xyz)=0
	This function will be called when DI-Guy Author nneds to know the world position behind the given screen coordinate. More...

virtual int	convert_world_to_screen (const diguyVec3f &world_xyz, diguyVec3f *screen_xyz)=0
	This function is the inverse of convert_screen_to_world(). More...

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

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.
int	set_author_ui_window_visible (const char *window_name, int visible)
	Calling this function will tell the DI-Guy Author UI to show or hide the specified window. More...

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. More...

int	set_author_ui_panel_visible (const char *panel_name)
	Calling this function will tell the DI-Guy Author UI to show the specified panel in the elements window. More...

int	set_author_ui_select_crowd_character (diguyCharacter *character)
	Calling this function will tell the DI-Guy Author UI to select the specified character in the crowd page. More...

int	set_author_ui_select_code_browser_script (diguyCharacter *character)
	Calling this function will tell the DI-Guy Author UI to select the specified script for the character. More...

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.
virtual void	author_ui_window_visibility_changed (const char *window_name, int is_visible)
	Called if the named window in the Author UI application changes visibility state. More...

Static Public Member Functions
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.
static int	generate_sphere_vertices (float radius, int num_slices, int num_layers, const diguyVec3f &position_offset, const diguyVec3f &orientation, int num_vertices, diguyVec3f vertices, diguyVec3f normals, diguyVec2f texture_indices, int indices_for_wireframe, int num_indices, unsigned int **indices)
	Generates vertices for a sphere with the passed radius. More...

static int	generate_cone_vertices (float radius, float height, int num_slices, int num_layers, const diguyVec3f &position_offset, const diguyVec3f &orientation, int num_vertices, diguyVec3f vertices, diguyVec3f normals, diguyVec2f texture_indices, int indices_for_wireframe, int num_indices, unsigned int **indices)
	Similar to generate_sphere_vertices(), but for cones. More...

static int	generate_cylinder_vertices (float radius, float height, int num_slices, int num_layers, const diguyVec3f &position_offset, const diguyVec3f &orientation, int num_vertices, diguyVec3f vertices, diguyVec3f normals, diguyVec2f texture_indices, int indices_for_wireframe, int num_indices, unsigned int **indices)
	Similar to generate_sphere_vertices(), but for cylinders. More...

static int	generate_box_vertices (diguyVec3f min, diguyVec3f max, const diguyVec3f &position_offset, const diguyVec3f &orientation, int num_vertices, diguyVec3f vertices, diguyVec3f normals, diguyVec2f texture_indices, int indices_for_wireframe, int num_indices, unsigned int **indices)
	Similar to generate_sphere_vertices(), but for boxes, AKA rectangular solids. More...

static void	delete_generated_vertices (diguyVec3f vertices, diguyVec3f normals, diguyVec2f texture_indices, unsigned int indices)
	For deleting data generated by the various generate_*_vertices() functions. More...

Private Functions
The functions and variables past this point are for internal use only. No external access to them is expected or necessary.
class	bdiScenarioApp

class	bdiScenarioEditorInput

bdiScenarioEditorInput *	m_scripted_object

static diguyAuthorInterfaceCreateFunc *	s_create_func

bdiScenarioEditorInput *	get_scripted_object ()

	diguyAuthorInterface (void *internal_data)

virtual	~diguyAuthorInterface ()

Detailed Description

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.

Constructor & Destructor Documentation

diguyAuthorInterface::diguyAuthorInterface ( void * internal_data )

protected

virtual diguyAuthorInterface::~diguyAuthorInterface ( )

protectedvirtual

Member Function Documentation

diguyAuthorVisualRegionPaintbrush* diguyAuthorInterface::get_region_paintbrush ( )

Returns a pointer to the region paintbrush.

Returned pointer may be NULL.

void diguyAuthorInterface::set_mouse_screen_coordinates	(	int	x,
		int	y
	)

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.

Parameters

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

void diguyAuthorInterface::set_mouse_world_coordinates ( diguyVec3f world_coords )

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.

Parameters

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

void diguyAuthorInterface::set_mouse_button_l ( int button_state )

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.

Parameters

button_state 1 for down, 0 for up

void diguyAuthorInterface::set_mouse_button_r ( int button_state )

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

void diguyAuthorInterface::set_mouse_button_m ( int button_state )

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

void diguyAuthorInterface::set_mouse_wheel_change ( float mouse_wheel_change )

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.

Parameters

mouse_wheel_change (units documentation pending)

void diguyAuthorInterface::apply_mouse_inputs ( )

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.

void diguyAuthorInterface::set_keyboard_shift ( int key_state )

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.

Parameters

key_state 1 for down, 0 for up

void diguyAuthorInterface::set_keyboard_ctrl ( int key_state )

Same as set_keyboard_shift(), but for ctrl key.

void diguyAuthorInterface::set_keyboard_alt ( int key_state )

Same as set_keyboard_alt(), but for alt key.

void diguyAuthorInterface::set_key_pressed	(	int	key,
		int	key_state
	)

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.

Parameters

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

int diguyAuthorInterface::set_selected_diguy_uid ( long uid )

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.

Parameters

uid	unique identifier of selected object

Returns:

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

int diguyAuthorInterface::set_selected_diguy_uid_from_string ( const char * uid_string )

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

int diguyAuthorInterface::get_uid_base_type ( long uid )

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.

Parameters

uid	unique identifier to be checked

Returns:

uid base type enumeration

int diguyAuthorInterface::get_uid_base_type_from_string ( const char * uid_string )

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

diguyCharacter* diguyAuthorInterface::get_selected_character ( )

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

Returns:

pointer to type diguyCharacter

diguyCharacterPath* diguyAuthorInterface::get_selected_character_path ( )

diguyCharacterPath version of get_selected_character().

diguyWaypoint* diguyAuthorInterface::get_selected_waypoint ( )

diguyWaypoint version of get_selected_character().

diguyPathShape* diguyAuthorInterface::get_selected_path_shape ( )

diguyPathShape version of get_selected_character().

diguyGraphicsLink* diguyAuthorInterface::get_selected_link ( )

diguyGraphicsLink version of get_selected_character().

diguyGraphicsShape* diguyAuthorInterface::get_selected_shape ( )

diguyGraphicsShape version of get_selected_character().

virtual int diguyAuthorInterface::convert_screen_to_world	(	const diguyVec3f &	screen_xyz,
		diguyVec3f *	world_xyz
	)

pure virtual

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.

Parameters

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

Returns:

1 if an intersection occurred, 0 if not

virtual int diguyAuthorInterface::convert_world_to_screen	(	const diguyVec3f &	world_xyz,
		diguyVec3f *	screen_xyz
	)

pure virtual

This function is the inverse of convert_screen_to_world().

It takes a world position and returns the corresponding screen coordinate.

Parameters

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

virtual float diguyAuthorInterface::get_altitude	(	float	x,
		float	y,
		float	old_z,
		float	from_height = `10.0f`,
		int *	valid_result = `NULL`
	)

pure virtual

virtual int diguyAuthorInterface::update_selected_objects ( const diguyVec3f & screen_xyz )

pure virtual

virtual int diguyAuthorInterface::check_z_clearance	(	const diguyVec3f &	pos,
		const float	radius,
		const float	ground_angle,
		float	z_clear_height,
		int	check_below = `1`
	)		const

pure virtual

int diguyAuthorInterface::set_author_ui_window_visible	(	const char *	window_name,
		int	visible
	)

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

Parameters

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"

int diguyAuthorInterface::get_author_ui_window_visible ( const char * window_name )

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

Parameters

window_name name of the window to show or hide

int diguyAuthorInterface::set_author_ui_panel_visible ( const char * panel_name )

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

Parameters

panel_name name of the window to show or hide

Currently valid window names are:

"Character"
"Crowd"

int diguyAuthorInterface::set_author_ui_select_crowd_character ( diguyCharacter * character )

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

Parameters

character name of the character to select in the crowd window

int diguyAuthorInterface::set_author_ui_select_code_browser_script ( diguyCharacter * character )

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

Parameters

character name of the character to select in the crowd window

virtual void diguyAuthorInterface::author_ui_window_visibility_changed	(	const char *	window_name,
		int	is_visible
	)

virtual

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

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

static

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.

Parameters

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

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

static

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.

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

static

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.

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

static

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.

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

static

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

bdiScenarioEditorInput* diguyAuthorInterface::get_scripted_object ( )

inline

Friends And Related Function Documentation

friend class bdiScenarioApp

friend

friend class bdiScenarioEditorInput

friend

Member Data Documentation

bdiScenarioEditorInput* diguyAuthorInterface::m_scripted_object

protected

diguyAuthorInterfaceCreateFunc* diguyAuthorInterface::s_create_func

staticprotected

The documentation for this class was generated from the following file:

c:/bdi/include/diguyAuthorInterface.h

Public Member Functions

Static Public Member Functions

Private Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation