SE CreateSpatialSearchBoundary

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE CreateSpatialSearchBoundary

extern SE_Return_Code
SE_CreateSpatialSearchBoundary
(
	SE_Encoding		encoding,	¹
const	SE_Search_Bounds	*	search_bounds,	²
	SE_Search_Bounds_Closure		search_bounds_closure,	³
	SE_Search_Type		search_quality,	⁴
	SE_Object_Inclusion		inclusion,	⁵
	SE_Search_Dimension		search_dimension,	⁶
	SE_Search_Boundary	*	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_RETCOD_SUCCESS	and the spatial search boundary is created.
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 memory allocation succeeded.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_C_ENUMERATION_VALUE_INVALID	set if an invalid search_bounds_closure, search_quality, inclusion, or search_dimension was specified, or
SE_STATCODE_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), the call failed for any other reason.

Parameters Notes

¹ - identifies the API implementation encoding 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 encoding is NULL, then the API implementation encoding to be used must be statically bound at compile time. See also SE_GetEncoding().

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

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

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

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

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

⁷ pointer to the newly created search boundary.