DATASERV (kapputils) functions


LIBRARY ROUTINE

kapu_inset - inset source object 2 into source object 1

LIBRARY CALL

int kapu_inset(
   kobject src1_obj,
   kobject src2_obj,
   int	   w_flag,
   int     w_pos,
   int	   h_flag,
   int     h_pos,
   int	   d_flag,
   int     d_pos,
   int	   t_flag,
   int     t_pos,
   int	   e_flag,
   int     e_pos,
   double  real,
   double  imag,
   int	   pad_is_valid,
   int     only_inset_valid,
   int     mapping,
   kobject dst_obj)

INPUT

OUTPUT

RETURN VALUE

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

DESCRIPTION

kapu_inset inserts the data from src2_obj into src1_obj at the specified position, replacing the data in src1_obj. The resulting destination object (dst_obj) size will be at least the size of src1_obj, and may be larger, depending on the specified offset values (w_pos, h_pos, d_pos, t_pos, e_pos) and the size of src2_obj.

The only_inset_valid parameter defines whether only data from src2 that is marked as valid by the validity mask is inset into src1. If only_inset_valid is FALSE, all data and the mask from src2 are inset into src1. If only_inset_valid is TRUE, the src2 mask is checked for each point, and only valid points are inset into src1. The src2 mask is not propagated to the destination.

Lkinset is based on implicit indexing. This means that if location or time data exist, the inset operation is not done in terms an interpretation of the location/time data values, but in terms of the implicit indexing of these data (which is specified by the width, height, depth, time, elements indices of the polymorphic data model).

If location and/or time data exist, src1_obj is considered the dominant object. So the location/time data and attributes from src1_obj will be propagated to the destination object. If location/time does not exist in the destination object, it will be created there.

If src2_obj contains location or time data, the inset operation will still be performed, but the location/time data from src2_obj will not be preserved.

The position in src1_obj where src2_obj will be inserted is initially obtained from the KPDS_SUBOBJECT_POSITION attribute stored in src2_obj. Then, for any flag (w_flag, h_flag, d_flag, t_flag, e_flag) that is TRUE, the position for the corresponding dimension is reset to the position value passed in (w_pos, h_pos, d_pos, t_pos, e_pos).

Padding - In some instances, padding is necessary to maintain the integrity of the polymorphic data model - for example when the final size of the destination object is larger than the base source object. The real and imag parameters passed in define the values that will be used when padding.

If padding occurs in the destination object, and the valid flag is TRUE, padded data is considered valid and, if the destination object contains a validity mask, the mask value is set accordingly. If the valid flag is FALSE, the padded data will be masked as invalid. In this case, if the destination object does not have a validity mask, one will be created.

Treatment of 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 and KAPU_USE_COMMON_MAP. If neither source objects has a map, 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 inset operation is performed. The destination object will not have a map.

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. Note that by selecting this mapping option, you are assuming that the value segments of both objects have valid indices into that map.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

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

SEE ALSO

kapputils(3)

COPYRIGHT

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