NAME

EVALUATE VIEW ORIENTATION MATRIX − calculate a transformation matrix that orients the View Reference Coordinate system in the World Coordinate system

SYNOPSIS

C Syntax

void
peval_view_ori_matrix ( vrp, vup, error_ind, m )
Ppoint∗vrp;view reference point
Pvec∗vup;view up vector
Pint∗error_ind;OUT error indicator
Pmatrixm;OUT view orientation matrix

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use EVALUATE VIEW ORIENTATION MATRIX to calculate a view orientation matrix, used to transform World Coordinates (WC) to View Reference Coordinates (VRC).  This matrix establishes the u and v VRC axes in relation to WC space.  The view orientation matrix calculated by this function can be passed as an argument to SET VIEW REPRESENTATION. 

See the descriptions of the functions SET VIEW REPRESENTATION and EVALUATE VIEW MAPPING MATRIX in this function reference for more information. 

C Input Parameters

vrpA pointer to a Ppoint structure containing x and y WCs that specify the view reference point.  Ppoint is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
} Ppoint;

vupA pointer to a Pvec structure containing x and y WC values that specify the view up vector.  Pvec is defined in phigs.h as follows:

typedef struct {
Pfloatdelta_x;/∗ x magnitude ∗/
Pfloatdelta_y;/∗ y magnitude ∗/
} Pvec;

C Output Parameters

error_ind
A pointer to the location to store the error number of any error detected by this function.

mThe 2D homogeneous (3 × 3) view orientation matrix.  Pmatrix is defined in phigs.h as follows:

typedef  Pfloat  Pmatrix[3][3];

Execution

If the input parameters are consistent and well defined, EVALUATE VIEW ORIENTATION MATRIX returns a 2D homogeneous (3 × 3) transformation matrix in the output parameter view orientation matrix.  This matrix transforms WC to VRC according to the values of the input parameters. 

The view reference point defines the point in WC space that is to be used as the origin of the VRC system.  It is specified as a 2D point in the z = 0 plane of the WC system and is usually a point on or near the object to be viewed. 

The view up vector defines the UP direction of the VRC system.  It is specified as a 2D vector relative to the view reference point.  This vector defines a direction in the WC z = 0 plane.  This direction becomes the v axis of the VRC system.  The n axis of VRC is parallel to the z axis of the WC system, and the u axis is determined so that u, v, and n axes form a right-handed coordinate system. 

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

160Ignoring function, the view up vector has length zero

September 02, 1992