api_get_entities
List of: Functions
Subjects: Model Topology
Contents: Kernel

Action: Gets all specified entities related to an entity.

Prototype: outcome api_get_entities (


ENTITY* ent, // entity to examine


ENTITY_LIST& ent_list, // returned related




// entities


ENTITY_ID topology_ids, // topological selection


ENTITY_ID geometry_ids, // geometrical selection


PAT_NEXT_TYPE include_pat // how to treat



= PAT_CAN_CREATE,
// patterned faces


AcisOptions* ao = NULL
// acis options


);

Includes: #include "kernel/acis.hxx"

#include "kernel/kernapi/api/api.hxx"

#include "kernel/kernapi/api/kernapi.hxx"

#include "kernel/kerndata/data/entity.hxx"

#include "kernel/kerndata/lists/lists.hxx"

#include "kernel/kernapi/api/acis_options.hxx"

#include "kernel/kernutil/law/pattern_enum.hxx"

#include "kernel/kerndata/top/alltop.hxx"

#include "kernel/kerndata/geom/allsurf.hxx"

#include "kernel/kerndata/geom/allcurve.hxx"

#include "kernel/sg_husk/query/q_wire.hxx"

#include "kernel/sg_husk/query/q_vert.hxx"

#include "kernel/kernapi/api/api.err"

#include "baseutil/debug/module.hxx"

Description: This comprehensive API behaves analogous to the collection of like API's that return the related entities of a specific entity, such as api_get_faces and api_get_edges. This API however allows the specification of multiple entity types to be returned from a single pass of the traversal algorithm. The entity selection is made by passing a bit mask of topological ids, and optionally geometrical ids, to the API. The bit masks are created by 'or-ing' the respective ids together, as the following example demonstrates:


ENTITY_ID topo_bits = FACE_ID | EDGE_ID;

ENTITY_ID geom._bits = SURFACE_ID | CURVE_ID;


The entity id bit masks are categorized into topology ids and geometry ids, and cannot be mixed. They are however, mutually exclusive within their respective groups.


The following topological ids are available:


BODY_ID, LUMP_ID, SHELL_ID, SUBSHELL_ID, WIRE_ID, FACE_ID, LOOP_ID, COEDGE_ID, EDGE_ID, VERTEX_ID


The following geometrical ids are available:


TRANSFORM_ID, APOINT_ID, PCURVE_ID, SURFACE_ID, CURVE_ID


Given a set of topological id selections, the traversal algorithm searches for the selected entities from the level of the input entity within the topological hierarchy, and works its way down, selecting all that are lower in the hierarchical order. When the selection set contains entity ids that are higher in the topological hierarchy than the input entity, then the higher-level entities that share the input entities are also selected.


Given a FACE input entity with LUMP_ID and LOOP_ID selection ids, for example, the algorithm would select the owning LUMP, ignoring others, and would halt the traversal after selecting all loops of the face since the LOOP_ID is the lowest selection id.


The algorithm does not traverse laterally and will simply select the input entity in this case. For example, given a FACE input entity and a FACE_ID selection, the input face would be returned.


The geometrical id selections drive the algorithm in the same manner and assume the same level in the hierarchy as their topological owners.


By default, patterned objects are included in the list of entities. In general, however, the parameter include_pat determines how this function deals with such objects. The user may specify any one of the following through this argument:


PAT_CAN_CREATE - (default) patterned objects are created if they do not already exist, and are included in the list.


PAT_NO_CREATE - only those patterned objects that have already been created are included in the list.


PAT_IGNORE - no patterned objects besides seed pattern objects are included in the list.

Library: kernel

Filename: kern/kernel/kernapi/api/kernapi.hxx

Effect: Read-only
PDF/KERN/16FNA.PDF
HTM/DATA/KERN/KERN/16FNA/0053.HTM