1vpSetVoxelField(3) Library Functions Manual vpSetVoxelField(3)
2
6 vpSetVoxelField, vpFieldOffset - define the size and location of a
7 voxel field
8
10 #include <volpack.h>
11 vpResult
13 vpSetVoxelField(vpc, field_num, field_size, field_offset, field_max)
14 vpContext *vpc;
15 int field_num;
16 int field_size;
17 int field_offset;
18 int field_max;
19 int
21 vpFieldOffset(voxel_ptr, field_name)
22 vpContext *vpc;
23 LITERAL field_name;
24
26 vpc VolPack context from vpCreateContext.
27 field_num
29 Field number for the field to define (first field is 0).
30 field_size
32 Size of the field in bytes.
33 field_offset
35 Number of bytes from the beginning of the voxel to the beginning
36 of the field.
37 field_max
39 Maximum possible value of the field.
40 voxel_ptr
42 Pointer to a C structure defining the fields in the voxel.
43 field_name
45 Literal name of the voxel field in the C structure.
46
48 vpSetVoxelField is used to define the size and location of each field
49 in a voxel. Once you have chosen the sizes and order for the voxel
50 fields, call vpSetVoxelSize once and then call vpSetVoxelField once for
51 each field. Each field has a unique field number (the field_num argu‐
52 ment); the first field is 0, the next is 1, and so on, up to one less
53 than the total number of fields defined with VpSetVoxelSize. The
54 field_max argument is used to determine the required size for lookup
55 tables indexed by the value in a particular field; the maximum field
56 value may be any number from 0 to the maximum unsigned integer repre‐
57 sentable by the field size.
58 If you have declared the layout of a voxel using a C structure then you
60 can use the sizeof operator and the vpFieldOffset macro to compute the
61 field sizes and offsets. vpFieldOffset returns the number of bytes
62 from the beginning of a C structure to the beginning of a particular
63 field in the structure. For example, the following code shows how to
64 declare the size and offset for one voxel field:
65 struct voxel {
66 char field0;
67 char field1;
68 short field2;
69 } *dummy_voxel;
70 #define SIZE_0 sizeof(char)
72 #define OFFSET_0 vpFieldOffset(dummy_voxel, field0)
73 #define MAX_0 127
74 vpSetVoxelField(vpc, 0, SIZE_0, OFFSET_0, MAX_0);
76 The size of each field must be 1, 2 or 4 bytes.
78 You must also obey any byte-alignment restrictions required by your
79 hardware. On many machines, two-byte fields must begin on a two-byte
80 boundary and four-byte fields must begin on a four-byte boundary.
81 The total size of a voxel may also need to be padded so that voxels
82 packed one after the other still obey the alignment restrictions.
83 If you declare your voxel as a C structure and use the sizeof
84 operator and the vpFieldOffset macro then you should always get
85 correct results. However, if you do not consider alignment
86 restrictions when choosing the voxel field ordering the compiler may
87 have to insert padding for you, resulting in wasted memory.
88 Some of the VolPack routines require you to declare fields of a
90 particular size in order to store their results. The functions to
91 precompute surface normals and gradient magnitudes (see
92 vpVolumeNormals(3), vpScanlineNormals(3), vpClassifyVolume(3),
93 vpClassifyScalars(3) and vpClassifyScanline(3)) can optionally store a
94 one-byte scalar value, a one-byte
95 gradient magnitude, and a two-byte surface normal value in each voxel.
96 The following constants defined in volpack.h give the corresponding
97 maximum field values: VP_SCALAR_MAX, VP_GRAD_MAX, and VP_NORM_MAX.
98 If you choose not to use these functions then there is no need to
99 declare these fields.
100 It is usually not necessary to declare a field for the voxel opacity
102 if the opacity can be computed from the other voxel fields. See
103 vpSetClassifierTable(3) for further discussion.
104 If the call to vpSetVoxelSize succeeds, any existing precomputed
106 volume data structures in the context are destroyed.
107
109 The current voxel field parameters can be retrieved with the following
110 state variable codes (see vpGeti(3)): VP_FIELD_SIZES, VP_FIELD_OFFSETS,
111 VP_FIELD_MAXES.
112
114 The normal return value is VP_OK. The following error return value is
115 possible:
116 VPERROR_BAD_VALUE
118 The field number, size or offset is out of range.
119
121 VolPack(3), vpCreateContext(3), vpSetVoxelSize(3)
122VolPack vpSetVoxelField(3)