DATASERV (kapputils) functions


LIBRARY ROUTINE

kapu_append - combine source data objects into single destination object

LIBRARY CALL

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)

INPUT

OUTPUT

RETURN VALUE

TRUE (1) on success, FALSE (0) otherwise

DESCRIPTION

The kapu_append function combines all data objects provided in the input data object array. The objects are combined in the order in which they appear in the array. The dimension flags (w_flag, h_flag, d_flag, t_flag, e_flag) specify which dimension the objects will be stacked along. One and only one of these flags can be true.

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.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

Destination object (dst_obj) only: The size of the value, mask and map data may be modified. Map, location, and time data may be removed or added.

RESTRICTIONS

none

MODIFICATION

9 Feb 1995 - Scott Wilson Set up to skip any objects with no value data segment.

FILES

$DATASERV/objects/library/kapputils/src/append.c

SEE ALSO

kapputils(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.