int kapu_append(
kobject *object_array,
int num_objects,
int w_flag,
int h_flag,
int d_flag,
int t_flag,
int e_flag,
int mapping,
kobject dst_obj)
Value Data Size & padding: the value (and mask) size of each source object will be padded to the maximum of all sizes - except in the stacking dimension. The pad value used for each source object will be the value defined by that object's pad value attribute. The highest data type of source data objects will be propagated to the destination value data. Any source object that has no value data will be skipped.
Map Data When some or all of the source objects have map data, the treatment of the maps, and how the data is represented in the destination object, depends on the mapping parameter passed in. Possible mapping options are KAPU_MAP_ALL_DATA, KAPU_CREATE_AUTOCOLOR_MAPS, and KAPU_USE_COMMON_MAP. If no source objects have maps, the mapping option is ignored. If there are doubts about which mapping option to use, the safest bet is to map the data thru the maps.
KAPU_MAP_ALL_DATA Map Data Thru Maps: All data will be mapped before the data objects are combined. The destination object will not have a map.
KAPU_CREATE_AUTOCOLOR_MAPS Create a Map for Each Input: (All source objects may have maps.) For each source object that does not have a map, one will be created for it. The the destination object color attributes will be copied from the first source object that has a map. New map values will be assigned using the KCOLOR_AUTOCOLOR attribute.
The map dimension corresponding to the stacking dimension (d_flag, t_flag, or e_flag) will reflect the new size of the value data in that dimension, and the maps from each object will be appended accordingly. The maximum width and height of all maps will be propagated to the destination, with zero-padding being applied where necessary. Padding in the other map dimensions may occur as well. For example, if objects with the following map and value Depth sizes are being stacked along the Depth dimension, obj1 DEP=3 MAP_DEP = 3 obj2 DEP=4 MAP_DEP = 1 obj2 DEP=2 MAP_DEP = 2 the resulting value data will have a depth of 9, so the map depth will be 9 too. In this example, the second object's map will be zero-padded to have a map depth of four.
If the objects are being combined along the width or height dimensions, the KAPU_CREATE_AUTOCOLOR_MAPS mapping option will fail.
KAPU_USE_COMMON_MAP Use First Map Only: In this case, the map data and color attributes of the first source object that has a map are directly transferred to the destination object. The depth, time, and elements dimensions of that map must be 1, otherwise this mapping option will fail. Note that by selecting this mapping option, you are assuming that the value segments of all objects being appended have valid indices into that map.
The destination object map data type will be the highest of the input object map data types.
Mask Data If any source object has mask data, then the destination object will also have mask data. The data will be resized in the same manner as value data is resized. The highest data type of source masks will be propagated to the destination mask.
Location and Time Data In all cases, the time and location data and/or attributes of the first object will transferred to the destination object. If location/time data is propagated, information along the stacking dimension will not be changed, and therefore, will most likely be corrupt.
Source & Destination Object Attributes This function only sets the data type, mapping mode, and the position attributes on references to the source objects. Therefore, other attributes already set for the source or destination object are used. For example, if the interpolate type is set to zero order (instead of the default of pad), when the object size is changed, pixel replication, not padding, will occur. This gives the calling routine more control over the append operation.
none
none
$DATASERV/objects/library/kapputils/src/append.c