vpLoadRawVolume(3)

💾 vpLoadRawVolume(3) — the load-your-volume-data-up era ✨

okay bestie, so this is a page from the Library Functions Manual for VolPack, and it's literally all about loading volume data structures from a file into your rendering context. it's giving "let me pull up your whole vibe from disk" energy and honestly? iconic. 🫶

---

🌸 NAME 🌸

vpLoadRawVolume, vpLoadMinMaxOctree, vpLoadClassifiedVolume, vpLoadContext — load volume data structures from a file

---

✨ SYNOPSIS ✨

#include <volpack.h>

vpResult
vpLoadRawVolume(vpc, fd)
    vpContext *vpc;
    int fd;

vpResult
vpLoadMinMaxOctree(vpc, fd)
    vpContext *vpc;
    int fd;

vpResult
vpLoadClassifiedVolume(vpc, fd)
    vpContext *vpc;
    int fd;

vpResult
vpLoadContext(vpc, fd)
    vpContext *vpc;
    int fd;

---

🎀 ARGUMENTS 🎀

• vpc — the VolPack context, the one you got from vpCreateContext. your main character fr.
• fd — a file descriptor from open(2), and it needs to be opened for reading. no write-mode nonsense here, bestie.

---

💖 DESCRIPTION 💖

so like, these functions are how you load volume data structures into a rendering context, from files that were written in the format produced by the VolPack file storing routines (peep vpStoreRawVolume(3) for that side of the story).

vpLoadRawVolume loads a 3D voxel array file. the file is carrying info about the size of the volume and the layout of the voxels, plus the volume data itself. a new voxel array gets allocated, the data gets read into that array, and the array gets stashed in the rendering context. 🫧

lowkey important: that array will not be freed automatically when the context is destroyed. no cap. the application is responsible for freeing the array when appropriate — by using vpGetp with the VP_VOXEL_DATA state variable code to retrieve the array pointer — or for unmapping the voxel array if it's been memory mapped (see below). don't leave it hanging, bestie. 😭

any existing min-max octree or preclassified volume data gets destroyed the moment vpLoadRawVolume is called. gone. the info loaded from the file includes all the parameters set with vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField and vpSetRawVoxels. and the data in the file gets automatically byte-swapped if the file was written on an architecture with a different byte ordering than the current architecture — a magic constant in the file is what decides if byte-swapping is necessary. 🔮

but heads up: volume fields that were not explicitly declared (by calling vpSetVoxelField before storing the voxel array file) cannot be byte-swapped. periodt.

vpLoadMinMaxOctree 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, so no sneaking mismatched data past it. 👀 any existing octree is destroyed and the new octree is stored in the rendering context. byte-swapping happens if it's necessary.

vpLoadClassifiedVolume loads a preclassified volume data file. the file includes info about the size of the volume and the layout of the voxels, plus the volume data itself. here's the vibe check:

• 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 get loaded.

the info loaded from the file includes all the parameters set with vpSetVolumeSize, vpSetVoxelSize and vpSetVoxelField. byte-swapping is performed if necessary. 💅

vpLoadContext 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 get loaded into dynamically allocated arrays, and — again, saying it louder for the people in the back — the application is responsible for freeing those arrays when necessary; they are not automatically freed when vpDestroyContext is called. 😤

🚨 in the current implementation, byte swapping is not performed, so context files from other architectures cannot be read. sorry babe, them's the rules.

---

🔧 the file-reading setup 🔧

the function used to read data from the files can be set by calling vpSetCallback with the VP_READ_FUNC option. this could be used to implement a file-compression system, for example — cute, right? 💅

it's 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. but 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. efficiency queen behavior. 👑

---

🌈 STATE VARIABLES 🌈

the current file I/O parameters can be retrieved with these state variable codes (see vpGeti(3)): VP_READ_FUNC, VP_MMAP_FUNC.

---

💀 ERRORS 💀

the normal return value is VP_OK. the following error return values are possible:

• VPERROR_IO — the file reading or memory mapping function returned an error value (in which case the external variable errno should contain an operating-system specific error code), or the end of the file was reached prematurely. 😭
• VPERROR_BAD_FILE — the data in the file is invalid, usually meaning that it isn't a file written by the appropriate VolPack function. not the file we were looking for, bestie. 🙈
• VPERROR_BAD_VOLUME — the data in a min-max octree file does not match the current volume size (vpLoadMinMaxOctree only).
• VPERROR_BAD_VOXEL — the data in a min-max octree file does not match the current voxel layout parameters (vpLoadMinMaxOctree only).

---

🦋 SEE ALSO 🦋

VolPack(3), vpCreateContext(3), vpStoreRawVolume(3)

---

and that's the whole page, babe 💜 this one came out of VolPack, and the version/date stamp on it is vpLoadRawVolume(3). go forth and load those volumes, you absolute legend. slay. ✨👑