.\" 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 vpTranspose 3 "" VolPack
.SH NAME
vpTranspose \- transpose a volume
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpTranspose(\fIvpc, axis\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
int \fIaxis;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIaxis\fR
Axis which should have the smallest stride after transposing
(VP_X_AXIS, VP_Y_AXIS or VP_Z_AXIS).
.SH DESCRIPTION
\fBvpTranspose\fR is used to transpose the 3D voxel array to optimize
the memory stride for a particular principal viewing axis.  The
intended way to use this function is to set the viewing
transformation, call \fBvpGeti\fR with the VP_VIEW_AXIS argument to
find the corresponding viewing axis, and then call \fBvpTranspose\fR
with that axis.  Transposing the data changes the arrangement of the
data stored in the 3D voxel array.  The voxel stride state variables
are updated to reflect this change, so the viewing transformation does
not need to be changed after transposing.  If the volume is already
transposed for the requested axis then it returns immediately without
modifying the voxel array.
.PP
This function is useful only for rendering large 3D voxel
arrays.  This function has no affect on the preclassified volume data.
.SH "STATE VARIABLES"
Relevant variables may be retrieved with the following state variable
codes (see vpGeti(3)): VP_VIEW_AXIS, VP_VOXEL_XSTRIDE, VP_VOXEL_YSTRIDE,
VP_VOXEL_ZSTRIDE.
.SH ERRORS
The normal return value is VP_OK.  The following error return values
are possible:
.IP VPERROR_BAD_OPTION
The \fIaxis\fR argument is invalid.
.IP VPERROR_BAD_VOLUME
The 3D voxel array is missing or invalid.
.IP VPERROR_BAD_VOXEL
The voxel fields are incorrectly specified.
.SH SEE ALSO
VolPack(3), vpCreateContext(3)