.\" 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 vpLoadRawVolume 3 "" VolPack .SH NAME vpLoadRawVolume, vpLoadMinMaxOctree, vpLoadClassifiedVolume, vpLoadContext \- load volume data structures from a file .SH SYNOPSIS #include .sp .FS vpResult \fBvpLoadRawVolume(\fIvpc, fd\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIfd;\fR .FE .sp .FS vpResult \fBvpLoadMinMaxOctree(\fIvpc, fd\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIfd;\fR .FE .sp .FS vpResult \fBvpLoadClassifiedVolume(\fIvpc, fd\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIfd;\fR .FE .sp .FS vpResult \fBvpLoadContext(\fIvpc, fd\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIfd;\fR .FE .SH ARGUMENTS .IP \fIvpc\fR VolPack context from \fBvpCreateContext.\fR .IP \fIfd\fR File descriptor from \fBopen\fR(2), open for reading. .SH DESCRIPTION These functions are used to load volume data structures into a rendering context from files in the format written by the VolPack file storing routines (see vpStoreRawVolume(3)). .PP \fBvpLoadRawVolume\fR loads a 3D voxel array file. The file includes information about the size of the volume and the layout of the voxels as well as the volume data itself. A new voxel array is allocated, the data is read into the array, and the array is stored in the rendering context. Note that the array will not be freed automatically when the context is destroyed; the application is responsible for freeing the array when appropriate (by using \fBvpGetp\fR with the VP_VOXEL_DATA state variable code to retrieve the array pointer), or for unmapping the voxel array if it has been memory mapped (see below). .PP Any existing min-max octree or preclassified volume data is destroyed when \fBvpLoadRawVolume\fR is called. The information loaded from the file includes all of the parameters set with \fBvpSetVolumeSize\fR, \fBvpSetVoxelSize\fR, \fBvpSetVoxelField\fR and \fBvpSetRawVoxels\fR. The data in the file is automatically byte-swapped if the file was written on an architecture with different byte ordering than the current architecture. A magic constant in the file is used to determine if byte-swapping is necessary. Volume fields that have not been explicitly declared (by calling \fBvpSetVoxelField\fR before storing the voxel array file) cannot be byte-swapped. .PP \fBvpLoadMinMaxOctree\fR loads a min-max octree file. The current 3D voxel array size and voxel layout must match the data in the octree file before the file is loaded; consistency checks are performed. Any existing octree is destroyed and the new octree is stored in the rendering context. Byte-swapping is performed if necessary. .PP \fBvpLoadClassifiedVolume\fR loads a preclassified volume data file. The file includes information about the size of the volume and the layout of the voxels as well as the volume data itself. If the volume matches the size and layout of any existing volume data in the rendering context then the data in the file replaces only the current preclassified volume; otherwise, the old octree is destroyed, the 3D voxel array parameters are zeroed out, and the new size and layout parameters are loaded. The information loaded from the file includes all of the parameters set with \fBvpSetVolumeSize\fR, \fBvpSetVoxelSize\fR and \fBvpSetVoxelField\fR. Byte-swapping is performed if necessary. .PP \fBvpLoadContext\fR loads a rendering context file. The file includes all rendering parameters except volume data and callback functions. The contents of any lookup tables for shading and classification are also loaded. Any existing preclassified volume data or octree are destroyed and the 3D voxel array parameters pointer is zeroed out. The lookup tables are loaded into dynamically allocated arrays, and the application is responsible for freeing those array when necessary; the arrays are not automatically freed when \fBvpDestroyContext\fR is called. In the current implementation byte swapping is not performed so context files from other architectures cannot be read. .PP The function used to read data from the files can be set by calling \fBvpSetCallback\fR with the VP_READ_FUNC option. This could be used to implement a file-compression system, for example. It is also possible to memory-map data from files by setting the VP_MMAP_FUNC option. If this function is set then large data structures are memory mapped from files instead of being copied into memory, when possible. Data that must be byte-swapped cannot be memory mapped. Memory mapping has the advantages that less swap space is required and data is loaded into memory only as it is used. .SH "STATE VARIABLES" The current file I/O parameters can be retrieved with the following state variable codes (see vpGeti(3)): VP_READ_FUNC, VP_MMAP_FUNC. .SH ERRORS The normal return value is VP_OK. The following error return values are possible: .IP VPERROR_IO The file reading or memory mapping function returned an error value (in which case the external variable \fBerrno\fR should contain an operating-system specific error code), or the end of the file was reached prematurely. .IP VPERROR_BAD_FILE The data in the file is invalid, usually meaning that it isn't a file written by the appropriate VolPack function. .IP VPERROR_BAD_VOLUME The data in a min-max octree file does not match the current volume size (\fBvpLoadMinMaxOctree\fR only). .IP VPERROR_BAD_VOXEL The data in a min-max octree file does not match the current voxel layout parameters (\fBvpLoadMinMaxOctree\fR only). .SH SEE ALSO VolPack(3), vpCreateContext(3), vpStoreRawVolume(3)