1vpRenderRawVolume(3) Library Functions Manual vpRenderRawVolume(3)
2
6 vpRenderRawVolume, vpRenderClassifiedVolume - render a volume
7
9 #include <volpack.h>
10 vpResult
12 vpRenderRawVolume(vpc)
13 vpContext *vpc;
14 vpResult
16 vpRenderClassifiedVolume(vpc)
17 vpContext *vpc;
18
20 vpc VolPack context from vpCreateContext.
21
23 These routines are used to render a volume using the parameters in a
24 rendering context. vpRenderRawVolume renders the data in the current
25 voxel array and stores the result in the current image array. If an
26 octree is present in the context (see vpCreateMinMaxOctree(3)) then it
27 is used to accelerate rendering. vpRenderClassifiedVolume is identical
28 in function except that it renders the current preclassified volume
29 (see vpClassifyVolume(3)) instead of the voxel array, and the octree is
30 not used.
31 vpRenderClassifiedVolume should be used when the same volume is ren‐
33 dered multiple times with the same opacity transfer function. This
34 rendering mode is the fastest. The opacity transfer function must not
35 change because the voxel opacities must be fixed to compute a preclas‐
36 sified volume.
37 vpRenderRawVolume should be used when the volume data or the opacity
39 transfer function changes in between renderings. If the volume data
40 remains fixed then a min-max octree should be computed to accelerate
41 rendering. Rendering is significantly faster with an octree than with‐
42 out, although it is still slower than rendering with vpRenderClassi‐
43 fiedVolume.
44 Before the rendering routines are called the rendering context must be
46 initialized to set the volume parameters, classification parameters
47 (vpRenderRawVolume only), viewing parameters, shading and lighting
48 parameters, and image array. See VolPack(3) for a list of relevant
49 functions.
50 One important state variable should be adjusted before calling the ren‐
52 dering routines: the maximum opacity threshold. This number specifies
53 a threshold value for the opacity of an image pixel. If the opacity of
54 the pixel reaches the threshold then no more voxels are composited into
55 the pixel. The threshold should be a number slightly less than one
56 (0.95 is a good value); numbers closer to 1.0 result in longer render‐
57 ing times, but less error. The value of the threshold is changed by
58 calling vpSetd with the VP_MAX_RAY_OPACITY option. The default value
59 is 1.0.
60 There are two additional state variables that can be adjusted to set
62 the size of an internal data structure. During rendering, a work buf‐
63 fer called the intermediate image is used to hold temporary results.
64 The size of this data structure depends on the size of the volume and
65 the current view transformation matrix. Over the course of an anima‐
66 tion sequence the intermediate image may have to be enlarged multiple
67 times, resulting in many calls to the memory allocator. Normally the
68 overhead of reallocating the data structure is negligible and can be
69 ignored. However, this overhead can be eliminated by specifying hints
70 for the maximum size of the intermediate image. The data structure
71 will then be allocated once, and will never be reallocated unless an
72 even larger intermediate image is required. To set the size hints,
73 call vpSeti with the VP_INT_WIDTH_HINT and VP_INT_HEIGHT_HINT state
74 variable codes. If the viewing transformation does not include any
75 scaling, then the maximum possible size of each dimension of the inter‐
76 mediate image is twice the size of the largest dimension of the volume.
77 To get a more precise bound, the intermediate image size required for
78 rendering a volume with the current viewing parameters can be found by
79 calling vpGeti with the VP_INTERMEDIATE_WIDTH and VP_INTERMEDI‐
80 ATE_HEIGHT state variable codes.
81
83 The normal return value is VP_OK. The following error return values
84 are possible:
85 VPERROR_BAD_SHADER
87 The shading lookup tables are sized incorrectly, or one of the
88 voxel fields used to index the tables is invalid, or the number
89 of material types is invalid.
90 VPERROR_SINGULAR
92 One of the current view transformation matrices is singular.
93 VPERROR_BAD_VOLUME
95 The volume size has not been set or is invalid, or there is no
96 volume data.
97 VPERROR_BAD_VOXEL
99 The voxel size or the voxel fields have not been specified or
100 have been incorrectly specified.
101 VPERROR_BAD_CLASSIFIER
103 The opacity transfer function tables have invalid sizes or are
104 associated with invalid voxel fields or have been incorrectly
105 specified. (vpRenderRawVolume only)
106 VPERROR_BAD_SHADOW
108 The angle between the shadow light vector and the viewing direc‐
109 tion is too large (must be less than 45 degrees). Either change
110 the light direction or disable shadows (see vpSetShadowLookup‐
111 Shader).
112
114 VolPack(3), vpCreateContext(3)
115VolPack vpRenderRawVolume(3)