MbufChildContainer

This function allocates a child container that behaves as though it contains components of the specified, previously allocated container. Which components are in the child container is determined dynamically by filtering the contents of the parent container using the specified criteria. Whenever the parent container is modified, MIL determines the current contents of the child container.

For example, child containers are useful for working with 3D sensors that transmit multiple sets of components. If your 3D sensor transmits 3 range and confidence components with different group IDs in a single grab, you can create a child container of the grab container with the criteria M_COMPONENT_BY_GROUP_ID(); this allocates a child container that only has the range and confidence components of a single group. Each time you grab into the parent container, the child container will be updated with the components of that group (even if components were reallocated). You can pass this child container as a source to MbufConvert3d().

You can create multiple child containers of a single parent container. You can also create a child container of a child container.

To allocate a child container, you must pass an array of criteria to ComponentCriteriaArrayPtr. If you set ControlFlag to M_ANY_CRITERIA, the child container will contain the components of the parent container which meet at least one of the criteria. If you set ControlFlag to M_ALL_CRITERIA, the child container will only contain the components of the parent container that meet all of the specified criteria. Once you have allocated the child container, you cannot change these criteria. To remove a component from the child container, you can either free the component from the parent container (using MbufFreeComponent()) or allocate a child container of the child container that has additional criteria. To add a component to the child container, you must allocate a new component for the parent container (using MbufAllocComponent()) that meets the existing criteria.

A component of a child container is not allocated in its own memory space; it remains a component of the parent container. Therefore, any modification to a component in the child container affects that component in the parent and vice versa.

A child container is considered a container in its own right, and can be used in some of the same circumstances as its parent container. You cannot directly allocate or free components of a child container. A child container therefore cannot be passed as a destination for a grab, copy, or processing function; it can, however, be passed as a source to relevant functions.

A child container inherits its attributes (such as M_DISP) from the parent container.

When a child container is no longer required, it can be released using MbufFree(). Before a container can be freed, all of its child containers must also be freed.