.\" 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 -- function start .\" 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 vpSetVoxelField 3 "" VolPack .SH NAME vpSetVoxelField, vpFieldOffset \- define the size and location of a voxel field .SH SYNOPSIS #include .sp .FS vpResult \fBvpSetVoxelField(\fIvpc, field_num, field_size, field_offset, field_max\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIfield_num;\fR .FA int \fIfield_size;\fR .FA int \fIfield_offset;\fR .FA int \fIfield_max;\fR .FE .sp .FS int \fBvpFieldOffset(\fIvoxel_ptr, field_name\fB)\fR .FA vpContext *\fIvpc;\fR .FA LITERAL \fIfield_name;\fR .FE .SH ARGUMENTS .IP \fIvpc\fR VolPack context from \fBvpCreateContext.\fR .IP \fIfield_num\fR Field number for the field to define (first field is 0). .IP \fIfield_size\fR Size of the field in bytes. .IP \fIfield_offset\fR Number of bytes from the beginning of the voxel to the beginning of the field. .IP \fIfield_max\fR Maximum possible value of the field. .IP \fIvoxel_ptr\fR Pointer to a C structure defining the fields in the voxel. .IP \fIfield_name\fR Literal name of the voxel field in the C structure. .SH DESCRIPTION \fBvpSetVoxelField\fR is used to define the size and location of each field in a voxel. Once you have chosen the sizes and order for the voxel fields, call \fBvpSetVoxelSize\fR once and then call \fBvpSetVoxelField\fR once for each field. Each field has a unique field number (the \fIfield_num\fR argument); the first field is 0, the next is 1, and so on, up to one less than the total number of fields defined with \fIVpSetVoxelSize\fR. The \fIfield_max\fR argument is used to determine the required size for lookup tables indexed by the value in a particular field; the maximum field value may be any number from 0 to the maximum unsigned integer representable by the field size. .PP If you have declared the layout of a voxel using a C structure then you can use the \fIsizeof\fR operator and the \fBvpFieldOffset\fR macro to compute the field sizes and offsets. \fBvpFieldOffset\fR returns the number of bytes from the beginning of a C structure to the beginning of a particular field in the structure. For example, the following code shows how to declare the size and offset for one voxel field: .DS .ta 18 .nf struct voxel { char field0; char field1; short field2; } *dummy_voxel; #define SIZE_0 sizeof(char) #define OFFSET_0 vpFieldOffset(dummy_voxel, field0) #define MAX_0 127 vpSetVoxelField(vpc, 0, SIZE_0, OFFSET_0, MAX_0); .DE .PP The size of each field must be 1, 2 or 4 bytes. You must also obey any byte-alignment restrictions required by your hardware. On many machines, two-byte fields must begin on a two-byte boundary and four-byte fields must begin on a four-byte boundary. The total size of a voxel may also need to be padded so that voxels packed one after the other still obey the alignment restrictions. If you declare your voxel as a C structure and use the \fIsizeof\fR operator and the \fBvpFieldOffset\fR macro then you should always get correct results. However, if you do not consider alignment restrictions when choosing the voxel field ordering the compiler may have to insert padding for you, resulting in wasted memory. .PP Some of the VolPack routines require you to declare fields of a particular size in order to store their results. The functions to precompute surface normals and gradient magnitudes (see vpVolumeNormals(3), vpScanlineNormals(3), vpClassifyVolume(3), vpClassifyScalars(3) and vpClassifyScanline(3)) can optionally store a one-byte scalar value, a one-byte gradient magnitude, and a two-byte surface normal value in each voxel. The following constants defined in volpack.h give the corresponding maximum field values: VP_SCALAR_MAX, VP_GRAD_MAX, and VP_NORM_MAX. If you choose not to use these functions then there is no need to declare these fields. .PP It is usually not necessary to declare a field for the voxel opacity if the opacity can be computed from the other voxel fields. See vpSetClassifierTable(3) for further discussion. .PP If the call to \fBvpSetVoxelSize\fR succeeds, any existing precomputed volume data structures in the context are destroyed. .SH "STATE VARIABLES" The current voxel field parameters can be retrieved with the following state variable codes (see vpGeti(3)): VP_FIELD_SIZES, VP_FIELD_OFFSETS, VP_FIELD_MAXES. .SH ERRORS The normal return value is VP_OK. The following error return value is possible: .IP VPERROR_BAD_VALUE The field number, size or offset is out of range. .SH SEE ALSO VolPack(3), vpCreateContext(3), vpSetVoxelSize(3)