SEDRIS Reference Manual
APPENDIX A - Transmittal Access Level 0 API
Functions
SE DetermineSpatialInclusion
extern SE_Return_Code
SE_DetermineSpatialInclusion
(
SE_Object test_object,1
constSE_Search_Bounds *search_bounds,2
SE_Search_Bounds_Closure search_bounds_closure,3
SE_Search_Type search_quality,4
SE_Search_Dimension search_dimension,5
SE_Boolean *object_fully_included,6
SE_Boolean *object_partly_included,7
SE_Boolean *object_includes_search_bounds8
);

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
  1. an invalid boundary was specified by the bounds parameter (e.g., the minimal and maximal points aren't in the same SRF), or
  2. the determination of the object / search area relationship couldn't be made, or
  3. the call failed for any other reason.

Parameters Notes

1 the object to test for inclusion.

2 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.

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

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

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

6 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.

7 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.

8 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).


Prev: SE_CreateStore. Next: SE_FreeIterator. Up:Index.

Last updated: July 26, 2006 Copyright © 2006 SEDRIS