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
pevalvieworientationmatrix3 ( vrp, vpn, vup, error_ind, matrix )
Ppoint3∗vrp;view reference point
Pvector3∗vpn;view plane normal
Pvector3∗vup;view up vector
Pint∗error_ind;OUT error indicator
Pmatrix3matrix;OUT view orientation matrix

FORTRAN Syntax

SUBROUTINE pevom3 ( VWRX, VWRY, VWRZ, VPNX, VPNY, VPNZ, VUPX, VUPY, VUPZ, ERRIND,
    VWORMT )
REALVWRX, VWRY, VWRZ view reference point (WC)
REALVPNX, VPNY, VPNZ view plane normal (WC)
REALVPUPX, VUPY, VUPZ view up vector (WC)
INTEGERERRINDOUT error indicator
REALVWORMT(4, 4)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 {
Pfloat  x;/∗ x coordinate ∗/
Pfloat  y;/∗ y coordinate ∗/
Pfloat  z;/∗ z coordinate ∗/
} Ppoint3;

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

typedef struct {
Pfloat  x;/∗ x magnitude ∗/
Pfloat  y;/∗ y magnitude ∗/
Pfloat  z;/∗ z magnitude ∗/
} Pvector3;

vupA pointer to a Pvector3 structure containing x, y, and z world coordinate values that specify the view up vector.  Pvector3 is defined in phigs.h as follows:

typedef struct {
Pfloat  x;/∗ x magnitude ∗/
Pfloat  y;/∗ y magnitude ∗/
Pfloat  z;/∗ z magnitude ∗/
} Pvector3;

C Output Parameters

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

matrixThe 3-D homogeneous (4 x 4) view orientation matrix.  Pmatrix3 is defined in phigs.h as follows:

typedef  Pfloat  Pmatrix3[4][4];

FORTRAN Input Parameters

VWRX, VWRY, VWRZ
The x, y and z world coordinates that specify the view reference point. 

VPNX, VPNY, VPNZ
The x, y and z world coordinate values that specify the view plane normal vector. 

VUPX, VUPY, VUPZ
The x, y and z world coordinate values that specify the view up vector. 

FORTRAN Output Parameters

ERRIND
The error number of any error detected by this function.

VWORMT
The 3-D homogeneous (4 x 4) view orientation matrix.

Execution

If the input parameters are consistent and well-defined, EVALUATE VIEW ORIENTATION MATRIX 3 returns a 3-D homogeneous (4 x 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 3-D world coordinate point and is usually a point on or near the object to be viewed. 

The view plane normal is a 3-D 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 3-D 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

Sun Release 4.0  —  Last change: 20 October 1988