.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford
.\" Junior University.  All rights reserved.
.\" 
.\" Permission to use, copy, modify and distribute this software and its
.\" documentation for any purpose is hereby granted without fee, provided
.\" that the above copyright notice and this permission notice appear in
.\" all copies of this software and that you do not sell the software.
.\" Commercial licensing is available by contacting the author.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\" 
.\" Author:
.\"    Phil Lacroute
.\"    Computer Systems Laboratory
.\"    Electrical Engineering Dept.
.\"    Stanford University
.\" 
.\" $Date: 1994/12/31 19:49:53 $
.\" $Revision: 1.1 $
.\"
.\" Macros
.\" .FS <type>  --  function start
.\"     <type> is return type of function
.\"     name and arguments follow on next line
.de FS
.PD 0v
.PP
\\$1
.HP 8
..
.\" .FA  --  function arguments
.\"     one argument declaration follows on next line
.de FA
.IP " " 4
..
.\" .FE  --  function end
.\"     end of function declaration
.de FE
.PD
..
.\" .DS  --  display start
.de DS
.IP " " 4
..
.\" .DE  --  display done
.de DE
.LP
..
.TH vpCurrentMatrix 3 "" VolPack
.SH NAME
vpCurrentMatrix \- choose the current transformation matrix
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpCurrentMatrix(\fIvpc, option\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fIoption;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIoption\fR
A code specifying one of the VolPack transformation matrices
(VP_MODEL, VP_VIEW or VP_PROJECT).
.SH DESCRIPTION
\fBvpCurrentMatrix\fR is used to choose the current transformation
matrix.  The \fIoption\fR parameter must be one of the following:
.DS
.ta 15
VP_MODEL	modeling transformation
.br
VP_VIEW		viewing transformation
.br
VP_PROJECT	projection transformation
.DE
Subsequent calls to the matrix transformation functions
(\fBvpIdentityMatrix, vpTranslate, vpRotate, vpScale, vpMultMatrix\fR
and \fBvpSetMatrix\fR) are applied to the new current transformation
matrix.
.PP
Typically the modeling transformation is used to specify a
transformation from object coordinates to world coordinates.  In
object coordinates the volume data is located inside a unit cube
centered at the origin (corners at (-0.5, -0.5, -0.5) and (0.5, 0.5,
0.5)).  The default modeling transformation is the identity, so the
volume is initially located inside the unit cube in world coordinates.
By default, the current matrix is VP_MODEL.
The modeling transformation is also applied to light direction
vectors (see vpSetLight(3)).
.PP
The viewing transformation is used for transforming world coordinates
into eye coordinates.  In eye coordinates the viewer is looking down
the Z axis in the negative direction.  The default value of the matrix
is also the identity, so the viewer is looking down the Z axis in
world coordinates as well.  Typically this transformation
matrix is used to specify the location and direction of the viewer.
It is also possible to combine the modeling and viewing matrices (as
in the OpenGL viewing model), in which case you can store the
composite transformation in either the model or the view matrix set
the other matrix to the identity.
.PP
The projection transformation specifies the transformation from eye
coordinates to clip coordinates.  In the clip coordinate system the
entire viewing frustum lies inside a cube defined by the planes X=1,
X=-1, Y=1, Y=-1, Z=1 and Z=-1.  This transformation also specifies
the type of projection used to produce a 2D image.  The 2D image is
computed by projecting along the Z axis in the clip coordinate system
and then scaling in the X and Y dimensions to the final image size.
The routines \fBvpWindow\fR and \fBvpWindowPHIGS\fR are useful for
computing projection transformations.
.SH "STATE VARIABLES"
The current transformation matrix code can be retrieved with the following
state variable codes (see vpGeti(3)): VP_CURRENT_MATRIX.
.SH ERRORS
The normal return value is VP_OK.  The following error return value
is possible:
.IP VPERROR_BAD_OPTION
The \fIoption\fR argument is invalid.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpGetMatrix(3)