Graphics Functions

PCL and Customization > Basic Functions > Graphics Functions

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

Graphics Functions

Graphics Manager

PatranPatran provides a set of PCL callable routines which can be used to draw graphical primitives into the graphics windows. These routines were developed so programmers can provide graphical feedback to the user.

The graphics routines were written at a high level to free the developer from having to worry about the current view or which viewport to draw the graphics (there is a way to direct graphics to a specific viewport). All coordinates to the graphical routines are specified in world space.

Retained Graphics

The graphical primitives generated from the graphics routines can either be stored in the display list or drawn only to the viewports and not stored. For more information about primitives, see Graphics Primitives, 178.The advantage of stored (retained) graphics is that when the view changes, the primitives will automatically be redrawn in the current view orientation. Unretained graphics would not be redrawn when the view changes. The application would have to take care of redrawing the graphics.

The method by which the graphical primitives can be stored in the display list is through the use of segments. Any number of segments can be created in the graphics manager. Each segment can contain thousands of graphical primitives (lines, text, markers). Segment Routines, 176 contain the routines necessary for creating segments. When drawing graphics into a segment, the graphics will automatically show up in all viewports that contain the current group. As an example, if the user currently has two viewports posted, one for the top view and one for a side view of a group, any graphical feedback that is generated from within a segment will automatically be drawn to both viewports.

Example

Here is an example PCL showing how to draw a red box into a viewport. The box is placed in a segment:

REAL corner1(3), corner2(3), corner3(3), corner4(3)

INTEGER segment_id, color

color = 1

corner1(1) = 0.0

corner1(2) = 0.0

corner1(3) = 0.0

corner2(1) = 5.0

corner2(2) = 0.0

corner2(3) = 0.0

corner3(1) = 5.0

corner3(2) = 5.0

corner3(3) = 0.0

corner4(1) = 0.0

corner4(2) = 5.0

corner4(3) = 0.0

/*

 * Create segment. Segment ID is returned from graphics manager.

*/

gm_segment_create( segment_id )

/*

 * Draw lines. Lines will be retained in segment.

*/

gm_draw_line( segment_id, color, corner1, corner2 )

gm_draw_line( segment_id, color, corner2, corner3 )

gm_draw_line( segment_id, color, corner3, corner4 )

gm_draw_line( segment_id, color, corner4, corner1 )

/*

 * Make sure all graphics have been flushed to the screen.

*/

gm_segment_flush()

Segment Routines

These are the routines used to create, delete, and flush segments (PCL syntax shown):


gm_segment_create	( id )


Description:
To create a segment of graphics primitives (lines, text, etc. ).
Input:
None.
Output:
INTEGER	id	Created segment ID.
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.


gm_segment_delete	( id )


Description:
To delete a segment and remove all graphics primitives (lines, text, etc. ) in the segment from out of the graphics windows.
Input:
INTEGER	id	Segment ID to delete.
Output:
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.


gm_segment_flush	( )


Description:
To flush all graphics primitives to the screen. All primitives, regardless of segment, will be flushed.
Input:
None.
Output:
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.

Graphics Primitives

These are the routines used to draw graphics to the viewports. The graphics primitives can optionally be placed into a segment (PCL syntax shown):


gm_draw_line	( segment_id, color_id, start, end )


Description:
Draw a line in segment or current viewport.
Input:
INTEGER	segment_id	Segment ID created from gm_segment_create.
INTEGER	color_id	Color of line (0-15).
REAL[3]	start	Starting location of line in world coord.
REAL[3]	end	Ending location of line in world coord.
Output:
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.


gm_draw_text	( segment_id, color_id, location, text )


Description:
Draw a string in segment or current viewport.
Input:
INTEGER	segment_id	Segment ID created from gm_segment_create.
INTEGER	color_id	Color of text (0-15).
REAL[3]	location	Location of line in world coord.
STRING	text	Text string. Currently limited to 31 characters.
Output:
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.


gm_draw_marker	( segment_id, color_id, location, type, size )


Description:
Draw a marker in a segment or current viewport.
Input:
INTEGER	segment_id	Segment ID created from gm_segment_create.
INTEGER	color_id	Color of marker (0-15).
REAL[3]	location	Location of marker in world coord.
INTEGER	type	Type of marker (1-dot, 2-circle, 3-X, 4-+, 5-filled circle, 6-square, 7-filled square, 8-triangle, 9-filled tri, 10-diamond, 11-filled diamond).
INTEGER	size	Size of marker (in pixels).
Output:
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.


gm_draw_result_arrow	(segment_id, color_id, loc, direction, size, anchor_style, string )


Description:
Draw a result arrow at the specified location in the segment or current viewport.
Input:
INTEGER	segment_id	Segment ID created from gm_segment_create.
INTEGER	color_id	Color of arrow.
REAL[3]	loc	Location of arrow in world coord.
REAL[3]	direction	Direction of arrow in world coord.
REAL	size	Size of arrow (percentage of model size).
INTEGER	anchor_style	Anchor style (1-base, 2-tip, 3-middle).
STRING	string	Text string.
Output:
None.
Error Conditions:
None.
Note:
The various anchor styles for the “anchor_style” argument are shown below. Base: 0--------> Tip: -------->0 Middle: -----0----> where the location value is marked as "0"


gm_draw_arrow	( segment_id, color_id, base, tip, head_size )


Description:
Draw an arrow at the specified base and tip in the segment or current viewport.
Input:
INTEGER	segment_id	Segment ID created from gm_segment_create.
INTEGER	color_id	Color of arrow (0-15).
REAL[3]	base	Base location of arrow in world coord.
REAL[3]	tip	Tip location of arrow in world coord.
REAL	head_size	Arrow head size (percentage of arrow length).
Output:
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
None.


Note:	The head size is a percentage of the arrow length with a value between 0.0 and 1.0.

Viewport Routines


gm_conv_world_to_device	( vp_id, world_pt, dev_pt )


Description:
Gets the min/max x, y, z coordinate values of the bounding box that encloses the entities displayed in the current viewport. The coordinate values returned are in the global (world) coordinate system.
Input:
vp_id.	integer	viewport id
world_pt	real (3)	xyz world coordinate
Output:
dev_pt	real (3)	xyz device coordinate
INTEGER	<Return Value>	Status of operation. 0 = Successful.
Error Conditions:
15000025	Error in finding the viewport in the graphics manager display list


Note:	The device coordinates are returned in floats (real). The z-value in device coordinates is to allow depth differentiation of points that map to the same x,y location on the screen. Larger z-values are in front of smaller z-values.


gm_viewports_refresh	( )


Description:
Refresh all of the viewports.
Input:
None.
Output:
None.
Error Conditions:
None.


gm_viewport_refresh	( )


Description:
Refresh current viewport.
Input:
None.
Output:
None.
Error Conditions:
None.


gm_viewport_center_get	( center )


Description:
Calculate the center of the current viewport.
Input:
None.
Output:
REAL	center	Center of the model.
Error Conditions:
None.


gm_viewport_world_limits_get	( limits )


Description:
Get the x, y and z minimum/maximum values of the model in world space.
Input:
None.
Output:
REAL(6)	limits	Returns 5% less than the minimum and 5% more than the maximum x, y and z coordinates of the model in world space.
Error Conditions:
None.


gm_viewport_subject_get	( persp_off, center, zoom )


Description:
Calculate the center of the current viewport.
Input:
None.
Output:
INTEGER	persp_off	If TRUE, this skips perspective. If FALSE, the perspective setting in the current viewport will be used.
REAL[2]	center	Center of subject space for the viewport.
REAL	ZOOM	Zoom factor for the subject space.
Error Conditions:
None.