Definition

Creates an iterator to (traverses over the list of)/(returns pointers to) component objects that meet the user specified conditions. This iterator starts at the 'top' of an 'aggregation tree'. Consider the start_object as the root of a tree. All of the components below the start_object will be searched, and the components of those components will be searched, and their components will be searched, etc., as far down (as many levels down) as the search filter specifies. If the search filter does not limit the 'depth' of the search with a maximum search depth rule, then the iterator will search until it has tested every object in the 'aggregation-tree' rooted by the start_object.

Objects returned by a component iterator will meet these conditions:

1. they are components, either directly or transitively, of the start_object. That is, they are contained within the aggregation tree that is rooted at the start_object.

2. they satisfy the rules specified in the search filter, if a search filter is defined for the iterator. If NULL is passed in for the search filter, then no filtering is applied, and only conditions (1) and (3) must be satisfied.

   A search filter can include a maximum search depth restriction. If such a restriction is applied, then the sub-tree rooted at the start_object will only be searched until that maximum search depth has been reached. Components beyond that depth will not be searched.

3. they fall within the bounds of the spatial search boundary, given the inclusion rules defined for that search boundary. If NULL is passed in for the search boundary, then no location based filtering is applied, and only conditions (1) and (2) must be satisfied.

If a start_object does not contain any component objects (or it contains component objects, but none of the components within the specified search depth meet the search filter and/or search boundary conditions), then a Component Iterator for that start_object, search filter, and search boundary will not return any objects. A Component Iterator would be created, but it would have a length of 0 and would not return any objects.

To get the next object from an iterator, call SE_GetNextObject().

To find out the remaining length of an iterator (the number of objects remaining inside the iterator), call SE_GetIterationLengthRemaining().

When finished with an iterator, free it with a call to the SE_FreeIterator() function. Iterators can be freed at any time (they can be freed before all of their objects have been returned, that is, before their remaining length == 0, if the user so desires).

See also SE_InitializeInheritedComponentIterator().

Returns

SE_RET_CODE_SUCCESS	and the iterator is initialized.
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 all operations succeeded.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_INPUT_OBJECT

set if start_object is currently unresolved.

SE_STAT_CODE_INACTIONABLE_FAILURE

set if itr_traversal is invalid, general_traversal_pattern is invalid, selection parameters are provided but are not valid, traversal order parameters are provided, but are not valid a search filter is provided, but is not a handle to a valid, active (i.e., unfreed) search filter, a search boundary is provided, but is not a legal, valid search boundary for the scope of start_object the start_object, search filter, and / or search boundary came from different API implementations, or the call fails for any other reason.

Parameters Notes

start_object

 the object whose components will be traversed.

boundary

 a spatial search boundary that will be used
    to filter this iterator's output.

filter

 a search filter that will be used to filter
    the output of this iterator.

directly_attach_table_components

 if SE_FALSE, then the actual
    SEDRIS objects will be examined by the consumer through the
    component iterators.

     However, if SE_TRUE, then the component iterators will
     automatically make the following adjustments to the object types
     returned through the API in the following special cases:

     1) If an <Attribute Set Index> would otherwise be returned by the
        component iterator, the <Attribute Set Index> object will be
        automatically replaced by the corresponding objects referenced
        by the primary (1st) <Attribute Set> of the referenced
        <Attribute Set Table Group>.

     2) If a <Colour Index> would otherwise be returned by the component
        iterator, the <Colour Index> object will be replaced by an
        <Inline Colour> containing the same <Primitive Colour> as the
        <Primitive Colour> that would have been referenced by the
        <Colour Index> (through the default <Colour Table> of the
        associated <Colour Table Group>).

     3) If a <Vertex with Component Indices> object references an
        element of a <Hierarchical Table> object (<Colour Entry Table>,
        <Location 3D Table>, <Property Table Reference Table>, <Reference
        Vector Table>, or <Texture Coordinate Table>), the following objects
        will be returned as directly attached components of the
        <Vertex with Component Indices> (effectively traversing up
        the aggregation tree in order to pull out the indexed object(s)
        from the appropriate <Hierarchical Table> and making them
        explicit components of the <Vertex with Component Indices> object):

        a) In the case of <Location 3D Table> elements, the indexed
           <Location 3D> component will be directly attached to the
           <Vertex with Component Indices> object.

        b) In the case of <Property Table Reference Table> elements, the
           indexed <Property Table Reference> component will be directly
           attached to the <Vertex with Component Indices> object.

        c) In the case of <Reference Vector Table> elements, the indexed
           <Reference Vector> component will be directly attached to the
           <Vertex with Component Indices> object.

        d) In the case of <Colour Entry Table> elements, and if the
           <Colour Entry Table> components are <Colours>, the indexed
           <Colour> will appear as an <Inline Colour> directly attached
           to the <Vertex with Component Indices>.  If the
           <Colour Entry Table> components are <Colour Sets>, the
           <Colour> components of the indexed <Colour Set> will appear as
           direct <Inline Colour> components of the
           <Vertex with Component Indices>.

        e) In the case of <Texture Coordinate Table> elements, and if the
           <Texture Coordinate Table> components are <Texture Coordinates>,
           the indexed <Texture Coordinate> will be directly attached to
           the <Vertex with Component Indices> object.  If the
           <Texture Coordinate Table> components are
           <Texture Coordinate Sets>, the <Texture Coordinate> components
           of the indexed <Texture Coordinate Set> will appear as direct,
           ordered components of the <Vertex with Component Indices>.

process_inheritance

 if true, then 'inherited components' will be
    inherited, and they will show up as components of the appropriate
    objects.  These 'inherited' components will be just as 'valid' as
    'direct' components, and they will satisfy the
    SE_COMPONENT_DRM_CLASS_MATCH, SE_COMPONENT_FIELD_MATCH, and
    SE_COMPONENT_RANGE_MATCH macros just as 'direct' components do.

transform_locations

 if true, then all <Location> objects will be
    transformed according to the transformations (<LSR Transformations>
    and/or <World Transformations>) encountered by the iterator.

follow_model_instances

 if true, then the iterator will search through
    the <Geometry Model Instance> to <Geometry Model> association as if
    it were an aggregation (it will 'instance' the model).  The same logic
    applies to the <Feature Model Instance> to <Feature Model> association.

evaluate_static_control_links

 if true, then all expressions composed
    entirely of literals and functions that use only literals will be
    evaluated, and their results will 'over-write' the appropriate
    fields of their targeted 'controlled' objects.

select_parameters_ptr

 a pointer to the parameters
    that will be used to determine that components to traverse when
    encountering a <Aggregate Feature> or <Aggregate Geometry> object.

traversal_order_parameters_ptr

 a pointer to the
    parameters that will be used to determine what order to traverse the
    components when encountering a <Aggregate Feature> or <Aggregate
    Geometry> object.

general_traversal_pattern

 the user must choose whether the Iterator
    should traverse the search space in a depth-first, breadth-first,
    or any-order-the-API-chooses manner.  The depth-first and breadth-first
    approaches allow for full transformation and inherited component
    information to be maintained at all times.  The API-chooses-an-order
    approach can be faster, possibly much faster, but there is no guarantee
    that any path was taken from the start_object to the returned objects,
    so it is possible for no context (an empty context) to be returned with
    the returned objects.

itr_traversal

 the user must choose how
    the iterator will behave when it encounters an Inter-Transmittal
    Reference (ITR). The iterator could automatically resolve such
    references and continue the search within the new transmittal;
    report all ITR references without resolving them; or just ignore
    them completely and continue to search within the current
    transmittal.

iterator_out_ptr

 a pointer to the freshly created component iterator
    that will iterate over the objects that meet the conditions
    described above.

Prev: SE_InitializeAssociateIterator. Next: SE_InitializeInheritedComponentIterator. Up:Index.

Last updated: July 16, 2004 Copyright © 2004 SEDRIS™