Definition

Determines whether a SEDRIS 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 SEDRIS 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 SEDRIS 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_STAT_CODE_SUCCESS	and the output parameters provided were set to the appropriate values, if valid parameters were passed in, and the relationship between the object and the boundary was determined.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and none of the output parameters are modified, if search_bounds_ptr is NULL, or if all the output parameters are NULL.
SE_STAT_CODE_UNRESOLVED_START_OBJECT	and all provided output parameters are set to SE_FALSE, if object_in is unresolved.
SE_STAT_CODE_UNRESOLVED_OBJECT	and the output parameters are set as for SE_STAT_CODE_UNRESOLVED_START_OBJECT, if an unresolved object was encountered and could not be resolved.
SE_STAT_CODE_FAILURE	and the output parameters are set as for SE_STAT_CODE_UNRESOLVED_START_OBJECT, if an invalid boundary was specified by the bounds parameter (e.g., the minimal and maximal points aren't in the same SRF), if an invalid search_bounds_closure, search_quality, or search_dimension was specified, or the determination of the object / search area relationship couldn't be made, or the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

object_in

 the object to test for inclusion.

search_bounds_ptr

 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.

search_bounds_closure

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

search_quality

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

search_dimension

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

object_fully_included_out_ptr

 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.

object_partly_included_out_ptr

 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.

object_includes_search_bounds_out_ptr

 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_out_ptr can only be true in
  the following cases:
  - search_dimension is set to SE_SEARCH_DIM_TWO_D and the object is
    an aggregate containing a <Feature Face>, <Surface Geometry>,
    <Property Grid>, or <Volume Geometry>

  - search_dimension is SE_SEARCH_DIM_THREE_D_ONLY 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: May 15, 2003 Copyright © 2003 SEDRIS™