Function Name: Create Spatial Search Boundary

Definition

Creates a search boundary to limit the scope of a component iterator's search; the search boundary can be used in a later call to SE_InitializeComponentIterator() to limit the spatial area that the iterator will search.

Spatial search boundaries can be freed at any time; a search boundary does not need to stay in existence until the iterator(s) that depend on that boundary are freed. (An iterator retains a copy of any search boundary used to initialize that iterator).

If no spatial search boundary is supplied, then the set of objects over which the iterator will iterate will be determined solely by the search rules and the starting object of the search.

Returns

SE_NULL_REQUIRED_PARAMETER - and no changes are made, if search_boundary_out_ptr or bounds_ptr was NULL.

SE_INVALID_OR_NULL_OBJECT - and *search_boundary_out_ptr is set to NULL, if object_in is not a handle to a valid, active (i.e., not freed) object, which provides a context for obtaining scoping SRF parameters.

SE_UNRESOLVED_START_OBJECT - and *search_boundary_out_ptr is set to NULL, if object_in is an unresolved SEDRIS object.

SE_OUT_OF_MEMORY - *search_boundary_out_ptr is set to NULL, if the API could not allocate memory for the new search boundary.

SE_FAILURE - and *search_boundary_out_ptr is set to NULL, if

1. an invalid boundary was specified by the bounds parameter (e.g., the minimal and maximal points aren't in the same SRF),
2. if an invalid search_bounds_closure, search_quality, inclusion, or search_dimension was specified, or
3. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

object_in

 an object, providing the context within which the search
    boundary will be used.

bounds_ptr

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

search_bounds_closure

 whether the spatial search area includes all its
    boundaries (fully closed) or only the lower endpoints (partly closed).
    See SE_SEARCH_BOUNDS_CLOSURE_ENUM for more details.

search_quality

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

inclusion

 whether the inclusion test for the search specifies only
    fully included objects (objects completely inside the search boundary)
    or partly included objects (which include fully included objects as a
    subset). See SE_INCLUSION_CHOICE_ENUM for more details.

search_dimension

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

search_boundary_out_ptr

 pointer to the newly created search boundary.