SE DetermineSpatialInclusion

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE DetermineSpatialInclusion

extern SE_Return_Code
SE_DetermineSpatialInclusion
(
	SE_Object		test_object,	¹
const	SE_Search_Bounds	*	search_bounds,	²
	SE_Search_Bounds_Closure		search_bounds_closure,	³
	SE_Search_Type		search_quality,	⁴
	SE_Search_Dimension		search_dimension,	⁵
	SE_Boolean	*	object_fully_included,	⁶
	SE_Boolean	*	object_partly_included,	⁷
	SE_Boolean	*	object_includes_search_bounds	⁸
);

Definition

Determines whether a DRM object is contained within the user-specified spatial area. SE_DetermineSpatialInclusion() supplements the normal method of filtering objects by spatial location, i.e. the use of search boundaries with component iterators (see SE_CreateSpatialSearchBoundary() ).

While SE_DetermineSpatialInclusion() can be used with any DRM object, its intended use is to find out more information about the relationship of an object returned by a component iterator to the search bounds used in that iterator. The canonical example is to have the component iterator created with a partial inclusion choice, then to check objects for full inclusion with SE_DetermineSpatialInclusion().

In addition to determining whether a DRM object is partly or completely inside the user-defined search bounds, this function, unlike an SE_Search_Boundary, will also determine whether a 2- or 3-dimensional object completely includes the spatial search area.

Returns

SE_RETCOD_SUCCESS	and the answers are returned within the out parameters.
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

set if valid parameters were passed in, and the relationship between the object and the boundary was determined.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_UNRESOLVED_INPUT_OBJECT	set if test_object is unresolved.
SE_STATCODE_UNRESOLVED_OUTPUT_OBJECT	set if an unresolved object was encountered and could not be resolved.
SE_STATCODE_C_ENUMERATION_VALUE_INVALID	set if an invalid search_bounds_closure, search_quality, or search_dimension was specified, or
SE_STATCODE_INACTIONABLE_FAILURE	set if an invalid boundary was specified by the bounds parameter (e.g., the minimal and maximal points aren't in the same SRF), or the determination of the object / search area relationship couldn't be made, or the call failed for any other reason.

Parameters Notes

¹ the object to test for inclusion.

² the boundary definition; defines the spatial search area by ranges in each of its coordinates. If the search is 2-D, then the height values are ignored. See SE_Search_Bounds for more details.

³ determines whether the spatial search area includes its boundaries. See SE_Search_Bounds_Closure for more details.

⁴ determines whether to use a point, bounding box, or exact search. See SE_Search_Type for more details.

⁵ whether 2D, 3D, or both kinds of objects are considered. See SE_Search_Dimension for more details.

⁶ a pointer to an SE_Boolean variable in the user's memory space, used to indicate whether the object is strictly included in the search bounds.

⁷ a pointer to an SE_Boolean variable in the user's memory space, used to indicate whether the object's intersection with the search bounds is non-empty. If NULL, no check is made for partial inclusion.

⁸ a pointer to an SE_Boolean variable in the user's memory space, used to indicate whether the object's intersection with the search bounds is the search area itself. Note that *object_includes_search_bounds can only be true in the following cases: - search_dimension is set to SE_SEARCHDIM_TWO_DIMENSIONAL_OR_SURFACE and the object is an aggregate containing a <Feature Face>, <Surface Geometry>, <Property Grid>, or <Volume Geometry> - search_dimension is SE_SEARCHDIM_THREE_DIMENSIONAL and the object is an aggregate containing a <Volume Geometry> or <Data Table>. Otherwise the question is meaningless (a point or linear object can't contain a region).