NAME

EVALUATE VIEW ORIENTATION MATRIX 3 − calculate a transformation matrix that orients the View Reference Coordinate (VRC) system in the World Coordinate (WC) system

SYNOPSIS

C Syntax

void
peval_view_ori_matrix3 ( vrp, vpn, vup, error_ind, m )
Ppoint3∗vrp;view reference point
Pvec3∗vpn;view plane normal
Pvec3∗vup;view up vector
Pint∗error_ind;OUT error indicator
Pmatrix3m;OUT view orientation matrix

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

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

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

C Input Parameters

vrpA pointer to a Ppoint3 structure containing x, y and z world coordinates that specify the view reference point.  Ppoint3 is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

vpnA pointer to a Pvec3 structure containing x, y, and z World Coordinate values that specify the view plane normal vector.  Pvec3 is defined in phigs.h as follows:

typedef struct {
Pfloatdelta_x;/∗ x magnitude ∗/
Pfloatdelta_y;/∗ y magnitude ∗/
Pfloatdelta_z;/∗ z magnitude ∗/
} Pvec3;

vupA pointer to a Pvec3 structure containing x, y, and z world coordinate values that specify the view up vector.  Pvec3 is defined above. 

C Output Parameters

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

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

typedef  Pfloat  Pmatrix3[4][4];

Execution

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

The view reference point defines the point in World Coordinate Space that is to be used as the origin of the View Reference Coordinate system.  It is specified as a 3D world coordinate point and is usually a point on or near the object to be viewed. 

The view plane normal is a 3D vector defined in World Coordinates relative to the view reference point.  It defines the n axis  of the VRC system.  The plane in WC that contains the view reference point and is perpendicular to the view plane normal is called the view reference plane. 

The view up vector is a 3D vector defined in World Coordinates relative to the view reference point.  The projection of this vector onto the view reference plane parallel to the view plane normal determines the v axis of the VRC system. 

The u axis of VRC is determined so that the uvn axes form a right-handed coordinate system. 

ERRORS

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

159Ignoring function, the view plane normal vector has length zero

160Ignoring function, the view up vector has length zero

161Ignoring function, the view up and view plane normal vectors are parallel thus the viewing coordinate system cannot be established

September 02, 1992