FACE
List of: Classes
Subjects: Model Topology, SAT Save and Restore
Contents: Kernel

Purpose: Represents a bounded portion of a SURFACE.

Derivation: FACE : ENTITY : ACIS_OBJECT : -

SAT Identifier: "face"

Filename: kern/kernel/kerndata/top/face.hxx

Description: A face is a bounded portion of a single geometric surface, the two-dimensional analog of a body. The boundary is represented by one or more loops or edges. Each face is simply connected, implying that one can traverse from any point on the interior of the face to any other point on the interior of the face without crossing the boundary of the face. In general, it is not meaningful to distinguish exterior and interior loops of edges, though for certain surface types this may be possible and some algorithms may do so.


Face loops need not necessarily be closed, and if not, either open end may be finite or infinite. If either end is infinite, then the face is infinite; if either end is finite, then the face is "incompletely-bounded", or just "incomplete." Although such faces can be represented in ACIS, most algorithms cannot handle such faces.


Users may also find the topological traversal functions located in kernel/kerndata/top/query.hxx useful for generating lists of faces on other topological entities or lists of edges and vertices on faces. The get_face_box function may be useful to retrieve or recalculate a face's bounding box. The reset_boxes function may be useful to reset the bounding box of a face and its parents. Other functions of note include:


point_in_face determines the containment of a point versus a face.

raytest_face determines the intersection of a ray with a face.

sg_get_face_normal Calculates a normal at a point on a face.

find_cls_ptto_face finds the closest point to a specified point on a face.

References: KERN LOOP, SHELL, SUBSHELL, SURFACE

by KERN LOOP, SHELL, SUBSHELL, pattern_holder
Constructor: public: FACE::FACE ();


C++ allocation constructor requests memory for this object but does not populate it. The allocation constructor is used primarily by restore. Applications should call this constructor only with the overloaded new operator, because this reserves the memory on the heap, a requirement to support roll back and history management.






public: FACE::FACE (


FACE*, // old FACE


LOOP*, // first loop


logical // update FACE list



= TRUE


);


C++ copy constructor requests memory for this object and populates it with the data from the object supplied as an argument. Applications should call this constructor only with the overloaded new operator, because this reserves the memory on the heap, a requirement to support roll back and history management.


Creates a FACE, using the given LOOP list, but taking geometry, senses, and shell and subshell owners from the old FACE. Optionally updates the SHELL or SUBSHELLFACE list to contain the new FACE (by default).






public: FACE::FACE (


LOOP*, // first LOOP


FACE*, // next FACE


SURFACE*, // SURFACE


REVBIT // sense


);


C++ initialize constructor requests memory for this object and populates it with the data supplied as arguments. Applications should call this constructor only with the overloaded new operator, because this reserves the memory on the heap, a requirement to support roll back and history management.


Creates a FACE. initializing the record and interfacing with the bulletin board. The arguments initialize the first LOOP on the face, the next FACE on the BODY, the underlying SURFACE geometry, and the sense of the FACE relative to the surface (FORWARD or REVERSED) respectively. It increments the SURFACE use count to reflect this new use. It also sets the backpointers (to the FACE) in the LOOPs that must be correctly chained together before this constructor is called. The calling routine must set shell_ptr or subshell_ptr to refer to the owning SHELL or SUBSHELL, and if desired, bound_ptr, using set_shell or set_subshell and set_bound.




Destructor: public: virtual void FACE::lose ();


Posts a delete bulletin to the bulletin board indicating the instance is no longer used in the active model. The lose methods for attached attributes are also called.






protected: virtual FACE::~FACE ();


This C++ destructor should never be called directly. Instead, applications should use the overloaded lose method inherited from the ENTITY class, because this supports history management. (For example, x=new FACE(...) then later x->lose.)



Methods: public: SPAbox* FACE::bound () const;


Returns a pointer to a geometric bounding region (a box), within which the entire FACE lies. The pointer is NULL if no such bound was calculated since the FACE was last changed.






protected: virtual logical


FACE::bulletin_no_change_vf (


ENTITY const* other,
// other entity


logical identical_comparator // comparator


) const;


Virtual function for comparing subclass data - called by bulletin_no_change. For the identical_comparator argument to be TRUE requires an exact match when comparing doubles and returns the result of memcmp as a default (for non-overridden subclasses). FALSE indicates tolerant compares and returns FALSE as a default.






public: CONTBIT FACE::cont () const;


Returns the containment of the face (BOTH_OUTSIDE or BOTH_INSIDE). This value is meaningless if the face is single-sided.






public: logical FACE::copy_pattern_down (


ENTITY* target
// target


) const;


Copies the pattern through all children of the target entity.






public: virtual void FACE::debug_ent (


FILE* // file pointer


) const;


Prints the type and address of this object, roll back pointer, attributes, and any unknown subtype information to the specified file. Refer to the ENTITY class for more details.






public: SURFACE* FACE::geometry () const;


Returns a pointer to the underlying SURFACE defining the FACE.






public: void FACE::get_all_patterns (


VOID_LIST& list
// pattern list


);


Returns all patterns.






public: virtual int FACE::identity (


int
// level



= 0


) const;


If level is unspecified or 0, returns the type identifier FACE_TYPE. If level is specified, returns FACE_TYPE for that level of derivation from ENTITY. The level of this class is defined as FACE_LEVEL.






public: virtual logical FACE::is_deepcopyable (


) const;


Returns TRUE if this can be deep copied.






public: LOOP* FACE::loop () const;


Returns a pointer to the first LOOP of COEDGEs bounding the FACE.






public: FACE* FACE::next (


PAT_NEXT_TYPE next_type // face type



= PAT_CAN_CREATE // for patterns


) const;


Returns the next face in a complete enumeration of all the faces in the shell.


The next_type argument controls how the next method treats patterns, and can take any one of three values:


PAT_CAN_CREATE: if the next face is to be generated from a pattern, create it if it doesn't yet exist and return its pointer.

PAT_NO_CREATE: if the next face is to be generated from a pattern, but hasn't yet been created, bypass it and return the pointer of the next already-created face (if any).

PAT_IGNORE: behave as though there is no pattern on the face.






public: FACE* FACE::next_in_list (


PAT_NEXT_TYPE next_type //



= PAT_CAN_CREATE //


) const;


Returns a pointer to the next FACE in the list of FACEs contained directly by a SHELL or SUBSHELL.






public: ENTITY* FACE::owner () const;


Returns a pointer to the owning entity.






public: logical FACE::patternable () const;


Returns TRUE.






public: logical FACE::remove_from_pattern ();


Removes the pattern element associated with this entity from the pattern. Returns FALSE if this entity is not part of a pattern element, otherwise TRUE.


Note The affected entities are not destroyed, but are merely made independent of the pattern. The pattern itself is correspondingly modified to "drop out" the newly disassociated element.






public: logical FACE::remove_from_pattern_list ();


Removes this entity from the list of entities maintained by its pattern, if any. Returns FALSE if no pattern is found, otherwise TRUE.






public: logical FACE::remove_pattern ();


Removes the pattern on this and all associated entities. Returns FALSE if no pattern is found, otherwise TRUE.






public: void FACE::restore_common ();


The RESTORE_DEF macro expands to the restore_common method, which is used in reading information from a SAT file. This method is never called directly. It is called by a higher hierarchical function if an item in the SAT file is determined to be of this class type. An instance of this class will already have been created through the allocation constructor. This method then populates the class instance with the appropriate data from the SAT file.


if (restore_version_number >= PATTERN_VERSION

read_ptr Pointer to record in save file for APATTERN on loop


if (apat_idx != (APATTERN*)(-1)))


restore_cache();

read_ptr Pointer to record in save file for next FACE in shell or subshell

read_ptr Pointer to record in save file for first LOOP bounding face

read_ptr Pointer to record in save file for SHELL containing face

read_ptr Pointer to record in save file for SUBSHELL containing face

read_ptr Pointer to record in save file for SURFACE on which face lies

read_logical ("forward", "reversed") Direction of face normal with respect to the surface

if (restore_version_number >= TWOSIDE_VERSION)

read_logical ("single", "double") Double sided face

if (sides_data) if double sided face


read_logical ("out", "in"), Double sided face containment. Containment data.

else containment data is FALSE.

else




Side data is SINGLE_SIDED and containment data is FALSE.






public: REVBIT FACE::sense () const;


Returns the sense of the FACE (FORWARD or REVERSED) relative to the SURFACE. Every SURFACE has a direction sense. Its normal direction is a continuous function of position. The normal to the FACE can be the same as that of the SURFACE at any position, or can be the reverse of it, as determined by sense. When a FACE bounds a region of space, its normal always points away from the region bounded.






public: REVBIT FACE::sense (


REVBIT rev // sense


) const;


Return the sense of the FACE compounded with the sense argument. Useful when traversing the FACE in a reverse direction.






public: void FACE::set_bound (


SPAbox* // bounding box


);


Sets the FACE's bounding SPAbox pointer to the given SPAbox. Before performing a change, it checks if the data structure is posted on the bulletin board. If not, the method calls backup to put an entry on the bulletin board.






public: void FACE::set_cont (


CONTBIT, // containment bit


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's containment bit to indicate whether the FACE is fully contained within the parent SHELL or not. Before performing a change, it checks if the data structure is posted on the bulletin board. If not, the method calls backup to put an entry on the bulletin board.






public: void FACE::set_geometry (


SURFACE*, // new SURFACE geometry


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's geometry pointer to the given SURFACE. A side effect of this method is the routine adjusts the use counts of the existing and new geometry and deletes the old if it is no longer referenced. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: void FACE::set_loop (


LOOP*, // new LOOP


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's loop pointer to the given LOOP. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: void FACE::set_next (


FACE*, // next FACE


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's nextFACE pointer to the given FACE. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: void FACE::set_pattern (


pattern* in_pat
// pattern


);


Set the current pattern.






public: void FACE::set_sense (


REVBIT, // sense


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's sense to FORWARD or REVERSED with respect to the SURFACE. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: void FACE::set_shell (


SHELL*, // SHELL


logical reset_pattern // reset or not


= TRUE //


);


Sets the FACE's SHELL pointer to the given SHELL. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: void FACE::set_sides (


SIDESBIT, // sidedness


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's sides to single or double sided. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: void FACE::set_subshell (


SUBSHELL*, // SUBSHELL


logical reset_pattern // reset or not


= TRUE


);


Sets the FACE's SUBSHELL pointer to the given SUBSHELL. Before performing a change, each routine checks whether the data structure is posted on the bulletin board. If not, the routine calls backup to put an entry on the bulletin board.






public: SHELL* FACE::shell () const;


Returns a pointer to the SHELL containing the FACE, either directly or through a hierarchy of SUBSHELLs.






public: SIDESBIT FACE::sides () const;


Returns SINGLE_SIDED if the FACE is single-sided, DOUBLE_SIDED if double-sided.






public: SUBSHELL* FACE::subshell () const;


Returns a pointer to the SUBSHELL containing FACE directly. The return is NULL if the FACE belongs directly to the owning SHELL.






public: virtual const char* FACE::type_name () const;


Returns the string "face".

Internal Use: next_face, save, save_common




Related Fncs: is_FACE
PDF/KERN/32CLF.PDF
HTM/DATA/KERN/KERN/32CLF/0001.HTM