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_STAT_CODE_SUCCESS	and a handle for the newly created search boundary is copied into *search_boundary_out_ptr, if valid parameters were passed in and memory allocation succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and no changes are made, if search_boundary_out_ptr or bounds_ptr was NULL.
SE_STAT_CODE_OUT_OF_MEMORY	*search_boundary_out_ptr is set to NULL, if the API could not allocate memory for the new search boundary.
SE_STAT_CODE_FAILURE	and *search_boundary_out_ptr is set to NULL, 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, inclusion, or search_dimension was specified, or the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

implementation_identifier

 - identifies the API implementation
    to use when creating this spatial search boundary.  If the specified API
    can't create the search boundary, then the API will return a status code
    indicating why it could not be created.  If implementation_identifier
    is NULL, then the API implementation to be used must be statically
    bound at compile time.

    See also SE_GetImplementationIdentifier().

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 for more details.

search_quality

 whether to use a point, bounding box, or exact search.
    See SE_Search_Type 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_Test for more details.

search_dimension

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

search_boundary_out_ptr

 pointer to the newly created search boundary.

Prev: SE_CreateSearchFilter. Next: SE_CreateStore. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™