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_RET_CODE_SUCCESS	and the answers are returned within the out parameters.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_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_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT	set if object_in is unresolved.
SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT	set if an unresolved object was encountered and could not be resolved.
SE_STAT_CODE_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), 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 call failed for any other reason.

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: July 16, 2004 Copyright © 2004 SEDRIS™