Polyhedral Data


Functions

void TecUtilDataFaceMapBeginAssign (FaceMap_pa FaceMap)
  Opens a face-mapping assignment context.
void TecUtilDataFaceMapAssignNodes (FaceMap_pa FaceMap, LgIndex_t NumFaces, const LgIndex_t *NumFaceNodes, const LgIndex_t *FaceNodes)
  Assigns the supplied face nodes to the open face-mapping assignment context.
void TecUtilDataFaceMapAssignElems (FaceMap_pa FaceMap, LgIndex_t NumFaces, const LgIndex_t *FaceLeftElems, const LgIndex_t *FaceRightElems)
  Assigns the supplied face left and right elements to the open face-mapping assignment context.
void TecUtilDataFaceMapAssignBConns (FaceMap_pa FaceMap, LgIndex_t NumBndryFaces, const LgIndex_t *NumBndryConns, const LgIndex_t *FaceBndryElems, const EntIndex_t *FaceBndryElemZones)
  Assigns the supplied boundary connected elements and zones to the open face-mapping assignment context.
Boolean_t TecUtilDataFaceMapEndAssign (FaceMap_pa FaceMap)
  Ends a face-mapping assignment sequence.
ArbParam_t TecUtilDataFaceMapGetClientData (FaceMap_pa FaceMap)
  Return the custom load-on-demand client data from a face map handle.
Boolean_t TecUtilDataFaceMapCustomLOD (EntIndex_t Zone, LgIndex_t NumFaces, LgIndex_t NumFaceNodes, LgIndex_t NumFaceBndryFaces, LgIndex_t NumFaceBndryConns, LoadOnDemandFaceMapLoad_pf LoadCallback, LoadOnDemandFaceMapUnload_pf UnloadCallback, LoadOnDemandFaceMapCleanup_pf CleanupCallback, ArbParam_t ClientData)
  Registers with Tecplot the load-on-demand callbacks and client data for a face mapping for a specific zone.
Boolean_t TecUtilDataFaceMapAlloc (EntIndex_t Zone, LgIndex_t NumFaces, LgIndex_t NumFaceNodes, LgIndex_t NumFaceBndryFaces, LgIndex_t NumFaceBndryConns)
  Allocates the space needed for the face mapping.
void TecUtilDataFaceMapAssignElemToNodeMap (FaceMap_pa faceMap, LgIndex_t numElements, const LgIndex_t *facesPerElem, const LgIndex_t *nodesPerFace, const LgIndex_t *elemToNodeMap)
  Assigns the nodes of each element to a polytope zone without having to provide the nodes and adjacent elements of each unique face, generating the required connectivity information.
LgIndex_t TecUtilDataFaceMapGetNFaces (FaceMap_pa FaceMap)
  Indicates how many faces comprise the specified face mapping.
LgIndex_t TecUtilDataFaceMapGetNFaceNodes (FaceMap_pa FaceMap, LgIndex_t Face)
  Indicates how many nodes comprise the specified face.
LgIndex_t TecUtilDataFaceMapGetFaceNode (FaceMap_pa FaceMap, LgIndex_t Face, LgIndex_t NodeOffset)
  Fetch a node from the face.
LgIndex_t TecUtilDataFaceMapGetLeftElem (FaceMap_pa FaceMap, LgIndex_t Face)
  The left element associated with the specified face.
LgIndex_t TecUtilDataFaceMapGetRightElem (FaceMap_pa FaceMap, LgIndex_t Face)
  The right element associated with the specified face.
LgIndex_t TecUtilDataFaceMapGetNBndryConns (FaceMap_pa FaceMap, LgIndex_t Face)
  Retrieves the number of boundary connections for the specified face.
void TecUtilDataFaceMapGetBndryConn (FaceMap_pa FaceMap, LgIndex_t Face, LgIndex_t BndryConnOffset, LgIndex_t *BndryElem, EntIndex_t *BndryElemZone)
  Fetch a connected element and its zone for a boundary face.
FaceMap_pa TecUtilDataFaceMapGetReadableRef (EntIndex_t Zone)
  Gets a readable face mapping for the specified polyhedral or polygonal zone of the current frame.
FaceMap_pa TecUtilDataFaceMapGetWritableRef (EntIndex_t Zone)
  Gets a writable face mapping for the specified polyhedral or polygonal zone of the current frame.
ElemToFaceMap_pa TecUtilDataElemGetReadableRef (EntIndex_t Zone)
  Gets a readable element-to-face mapping for the specified polyhedral or polygonal zone of the current frame.
LgIndex_t TecUtilDataElemGetNumFaces (ElemToFaceMap_pa ElemToFaceMap, LgIndex_t Elem)
  Gets the number of faces that comprise the specified polyhedral or polygonal element.
LgIndex_t TecUtilDataElemGetFace (ElemToFaceMap_pa ElemToFaceMap, LgIndex_t Elem, ElemFaceOffset_t FaceOffset)
  Gets the specified face number for the specified polyhedral or polygonal element.

Function Documentation

LgIndex_t TecUtilDataElemGetFace ( ElemToFaceMap_pa  ElemToFaceMap,
LgIndex_t  Elem,
ElemFaceOffset_t  FaceOffset 
)

Gets the specified face number for the specified polyhedral or polygonal element.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
ElemToFaceMap The element-to-face map handle
Elem The element for which to return the number of faces.
FaceOffset The face offset for which to return the face number. Must be in the range [1, n], where n is the number of faces returned by TecUtilDataElemGetNumFaces() for the specified element.
Returns:
The face number for the element.
Precondition:
ElemToFaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataElemGetFace (
   &           ElemToFaceMapPtr,
   &           Elem,
   &           FaceOffset)
    POINTER   (ElemToFaceMapPtr, ElemToFaceMap)
    INTEGER*4 Elem
    INTEGER*4 FaceOffset

Python Syntax:

  Results = TecUtil.DataElemGetFace(ElemToFaceMap, Elem, FaceOffset)

  Input:
                  ElemToFaceMap        opaque pointer
                  Elem                 int
                  FaceOffset           int
  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilDataElemGetNumFaces ( ElemToFaceMap_pa  ElemToFaceMap,
LgIndex_t  Elem 
)

Gets the number of faces that comprise the specified polyhedral or polygonal element.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
ElemToFaceMap The element-to-face map handle
Elem The element for which to return the number of faces.
Returns:
The number of faces that comprise the element.
Precondition:
ElemToFaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataElemGetNumFaces (
   &           ElemToFaceMapPtr,
   &           Elem)
    POINTER   (ElemToFaceMapPtr, ElemToFaceMap)
    INTEGER*4 Elem

Python Syntax:

  Results = TecUtil.DataElemGetNumFaces(ElemToFaceMap, Elem)

  Input:
                  ElemToFaceMap        opaque pointer
                  Elem                 int
  Output:
    Results[0]    ReturnVal            int

ElemToFaceMap_pa TecUtilDataElemGetReadableRef ( EntIndex_t  Zone  ) 

Gets a readable element-to-face mapping for the specified polyhedral or polygonal zone of the current frame.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
Zone Polyhedral or polygonal zone number.
Returns:
A readable element-to-face mapping for the specified polyhedral or polygonal zone or NULL if unsuccessful.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilDataElemGetReadableRef (
   &           Zone,
   &           ElemToFaceMapPtr)
    INTEGER*4 Zone
    POINTER   (ElemToFaceMapPtr, ElemToFaceMap)

Python Syntax:

  Results = TecUtil.DataElemGetReadableRef(Zone)

  Input:
                  Zone                 int
  Output:
    Results[0]    ReturnVal            opaque pointer

Boolean_t TecUtilDataFaceMapAlloc ( EntIndex_t  Zone,
LgIndex_t  NumFaces,
LgIndex_t  NumFaceNodes,
LgIndex_t  NumFaceBndryFaces,
LgIndex_t  NumFaceBndryConns 
)

Allocates the space needed for the face mapping.

Since:
11.2-1-0
Parameters:
Zone The zone needing the face mapping allocated.
NumFaces Total number of unique faces.
NumFaceNodes Total number of nodes for all faces. This is not the number of unique nodes but the total number. For example if a face map defined two triangles polygons that share a common face, NumFaces would be 5 and NumFaceNodes would be 6, not 4.
NumFaceBndryFaces Total number of faces boundary faces.
NumFaceBndryConns Total number of boundary face elements or boundary face element/zone pairs.
Returns:
TRUE if the face mapping was successfully allocated, FALSE otherwise.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapAlloc(
   &                   Zone,
   &                   NumFaces,
   &                   NumFaceNodes,
   &                   NumFaceBndryFaces,
   &                   NumFaceBndryConns)
    INTEGER*4       Zone
    INTEGER*4       NumFaces
    INTEGER*4       NumFaceNodes
    INTEGER*4       NumFaceBndryFaces
    INTEGER*4       NumFaceBndryConns

Python Syntax:

  Results = TecUtil.DataFaceMapAlloc(Zone, NumFaces, NumFaceNodes, NumFaceBndryFaces, NumFaceBndryConns)

  Input:
                  Zone                 int
                  NumFaces             int
                  NumFaceNodes         int
                  NumFaceBndryFaces    int
                  NumFaceBndryConns    int
  Output:
    Results[0]    ReturnVal            boolean

Allocate the face map of zone 3.

   IsOk = TecUtilDataFaceMapAlloc(3,
                                  NumFaces, NumFaceNodes,
                                  NumFaceBndryFaces, NumFaceBndryConns);

See also:
TecUtilDataConnectShare(), TecUtilDataFaceMapCustomLOD()

void TecUtilDataFaceMapAssignBConns ( FaceMap_pa  FaceMap,
LgIndex_t  NumBndryFaces,
const LgIndex_t *  NumBndryConns,
const LgIndex_t *  FaceBndryElems,
const EntIndex_t *  FaceBndryElemZones 
)

Assigns the supplied boundary connected elements and zones to the open face-mapping assignment context.

The boundary faces were assigned using a negative number for the left or right element of the face.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap An open face-mapping assignment context to which the boundary face elements (and zones if appropriate) are assigned.
NumBndryFaces The number of boundary faces being delivered.
NumBndryConns Array of boundary connection counts dimensioned by NumBndryFaces.
FaceBndryElems Array of boundary connected elements for the supplied faces dimensioned by the sum of the members of the NumBndryConns array. If only a portion of a boundary face has adjacent elements, use TECUTIL_NO_NEIGHBORING_ELEM for the first neighboring element, and follow this with the actual elements.
FaceBndryElemZones Array of zone numbers indicating which zone each of the elements in the FaceBndryElems array resides in. It has the same dimension as the FaceBndryElems array. For boundary faces that are only partially bounded by neighboring elements (indicated by TECUTIL_NO_NEIGHBORING_ELEM in the FaceBndryElems array), use TECUTIL_NO_NEIGHBORING_ZONE for the zone numbers corresponding to the 0-th entry in FaceBndryElems. Also use TECUTIL_NO_NEIGHBORING_ZONE to indicate the boundary element is in the current zone (do not use the current zone number).
Precondition:
FaceMap Pointer must be a valid address and non-NULL.

NumBndryConns Pointer must be a valid address and non-NULL.

FaceBndryElems Pointer must be a valid address and non-NULL.

FaceBndryElemZones Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapAssignBConns (
   &           FaceMapPtr,
   &           NumBndryFaces,
   &           NumBndryConns,
   &           FaceBndryElems,
   &           FaceBndryElemZones)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 NumBndryFaces
    INTEGER*4 NumBndryConns(*)
    INTEGER*4 FaceBndryElems(*)
    INTEGER*4 FaceBndryElemZones(*)

Python Syntax:

  Results = TecUtil.DataFaceMapAssignBConns(FaceMap, NumBndryFaces, NumBndryConns, FaceBndryElems, FaceBndryElemZones)

  Input:
                  FaceMap              opaque pointer
                  NumBndryFaces        int
                  NumBndryConns        list of ints
                  FaceBndryElems       list of ints
                  FaceBndryElemZones   list of ints
  Output:
    Results[0]    ReturnVal            NONE

void TecUtilDataFaceMapAssignElems ( FaceMap_pa  FaceMap,
LgIndex_t  NumFaces,
const LgIndex_t *  FaceLeftElems,
const LgIndex_t *  FaceRightElems 
)

Assigns the supplied face left and right elements to the open face-mapping assignment context.

The faces for the elements are implicitly given sequential face numbers. Calls to this routine may be intermingled with calls to TecUtilDataFaceMapAssignNodes. The only requirement is that the nodes and elements be delivered in the same order. That is, the nth face defined by TecUtilDataFaceMapAssignNodes must correspond to the nth pair of neighboring elements passed into TecUtilDataFaceMapAssignElems.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap An open face-mapping assignment context to which the face left and right elements are assigned.
NumFaces The number of faces being delivered.
FaceLeftElems Array of face left elements for the supplied faces dimensioned by NumFaces.
FaceRightElems Array of face right elements for the supplied faces dimensioned by NumFaces.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.

FaceLeftElems Pointer must be a valid address and non-NULL.

FaceRightElems Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapAssignElems (
   &           FaceMapPtr,
   &           NumFaces,
   &           FaceLeftElems,
   &           FaceRightElems)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 NumFaces
    INTEGER*4 FaceLeftElems(*)
    INTEGER*4 FaceRightElems(*)

Python Syntax:

  Results = TecUtil.DataFaceMapAssignElems(FaceMap, NumFaces, FaceLeftElems, FaceRightElems)

  Input:
                  FaceMap              opaque pointer
                  NumFaces             int
                  FaceLeftElems        list of ints
                  FaceRightElems       list of ints
  Output:
    Results[0]    ReturnVal            NONE

void TecUtilDataFaceMapAssignElemToNodeMap ( FaceMap_pa  faceMap,
LgIndex_t  numElements,
const LgIndex_t *  facesPerElem,
const LgIndex_t *  nodesPerFace,
const LgIndex_t *  elemToNodeMap 
)

Assigns the nodes of each element to a polytope zone without having to provide the nodes and adjacent elements of each unique face, generating the required connectivity information.

The assignment must be made for all elements of the zone at once. This function is used inside a face map load callback specified by TecUtilDataFaceMapCustomLOD().

If the number of faces in the zone (KMax) was not specified when the zone was created (see TecUtilDataSetAddZoneX()), this function will count the faces and set the target zone's KMax as a side effect.

This function is Thread Safe.

Note:
This function is mutually exclusive with calls to TecUtilDataFaceMapAssignNodes(), TecUtilDataFaceMapAssignElems() and TecUtilDataFaceMapAssignBConns(). These functions should be preferred if the nodes and adjacent element information is readily available.
Since:
12.1.1.7895
Parameters:
faceMap An open face-mapping assignment context that uses the element to node map to determine the nodes and elements for each unique face.
numElements The number of elements being represented by the accompanying arrays. This value must be the number of elements for the zone.
facesPerElem Array of the number of faces contained in each element.
nodesPerFace Array of the number of nodes contained in each face for each element. NULL for homogeneous polytope zones such as FEPolygon zones where the number of nodes per face is defined by the zone type.
elemToNodeMap Array of one based nodes for each polygonal element or the nodes for each face of each polyhedral element.
Precondition:
faceMap Pointer must be a valid address and non-NULL.

facesPerElem Pointer must be a valid address and non-NULL.

elemToNodeMap Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapAssignElemToNodeMap (
   &           faceMapPtr,
   &           numElements,
   &           facesPerElem,
   &           nodesPerFace,
   &           elemToFaceMap)
    POINTER   (faceMapPtr, faceMap)
    INTEGER*4 numElements
    INTEGER*4 facesPerElem(*)
    INTEGER*4 nodesPerFace(*)
    INTEGER*4 elemToFaceMap(*)

Python Syntax:

  Results = TecUtil.DataFaceMapAssignElemToNodeMap(faceMap, numElements, facesPerElem, nodesPerFace, elemToNodeMap)

  Input:
                  faceMap              opaque pointer
                  numElements          int
                  facesPerElem         list of ints
                  nodesPerFace         list of ints
                  elemToNodeMap        list of ints
  Output:
    Results[0]    ReturnVal            NONE

void TecUtilDataFaceMapAssignNodes ( FaceMap_pa  FaceMap,
LgIndex_t  NumFaces,
const LgIndex_t *  NumFaceNodes,
const LgIndex_t *  FaceNodes 
)

Assigns the supplied face nodes to the open face-mapping assignment context.

The faces for the nodes are implicitly given sequential face numbers. This function can deliver all the face nodes at once or one or more faces at a time. Calls to this routine may be intermingled with calls to TecUtilDataFaceMapAssignElems. The only requirement is that the nodes and elements be delivered in the same order. That is, the nth face defined by TecUtilDataFaceMapAssignNodes must correspond to the nth pair of neighboring elements passed into TecUtilDataFaceMapAssignElems.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap An open face-mapping assignment context to which the face nodes are assigned.
NumFaces The number of faces being delivered.
NumFaceNodes Array of face nodes counts dimensioned by NumFaces for ZoneType_FEPolyhedron, NULL for homogeneous polytope data such as ZoneType_FEPolygon where the number of nodes per face defined by the zone type.
FaceNodes Array of face nodes for the supplied faces dimensioned by the sum of the members of the NumFaceNodes array.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.

FaceNodes Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapAssignNodes (
   &           FaceMapPtr,
   &           NumFaces,
   &           NumFaceNodes,
   &           FaceNodes)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 NumFaces
    INTEGER*4 NumFaceNodes(*)
    INTEGER*4 FaceNodes(*)

Python Syntax:

  Results = TecUtil.DataFaceMapAssignNodes(FaceMap, NumFaces, NumFaceNodes, FaceNodes)

  Input:
                  FaceMap              opaque pointer
                  NumFaces             int
                  NumFaceNodes         list of ints
                  FaceNodes            list of ints
  Output:
    Results[0]    ReturnVal            NONE

void TecUtilDataFaceMapBeginAssign ( FaceMap_pa  FaceMap  ) 

Opens a face-mapping assignment context.

All face nodes and elements must be delivered between the face map begin/end assignment clause.

This function is Thread Safe.

Note:
This function should not be called in response to a custom face map load callback. For custom face map load callbacks Tecplot is responsible for allocating the face map, beginning an assignment context and ending it after the loader callback returns. The callback only need deliver face map information to Tecplot with calls to TecUtilDataFaceMapAssignBConns(), TecUtilDataFaceMapAssignElems(), TecUtilDataFaceMapAssignNodes() or TecUtilDataFaceMapAssignElemToNodeMap().
Since:
11.2-1-0
Parameters:
FaceMap Face mapping to which face nodes and elements are assigned.
Precondition:
Current frame must have a data set with at least one zone.

FaceMap Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapBeginAssign (
   &           FaceMapPtr)
    POINTER   (FaceMapPtr, FaceMap)

Python Syntax:

  Results = TecUtil.DataFaceMapBeginAssign(FaceMap)

  Input:
                  FaceMap              opaque pointer
  Output:
    Results[0]    ReturnVal            NONE

Boolean_t TecUtilDataFaceMapCustomLOD ( EntIndex_t  Zone,
LgIndex_t  NumFaces,
LgIndex_t  NumFaceNodes,
LgIndex_t  NumFaceBndryFaces,
LgIndex_t  NumFaceBndryConns,
LoadOnDemandFaceMapLoad_pf  LoadCallback,
LoadOnDemandFaceMapUnload_pf  UnloadCallback,
LoadOnDemandFaceMapCleanup_pf  CleanupCallback,
ArbParam_t  ClientData 
)

Registers with Tecplot the load-on-demand callbacks and client data for a face mapping for a specific zone.

Tecplot will notify the add-on via the callbacks when the face mapping needs to be loaded, unloaded, and cleaned up.

All callbacks must be written in a thread-safe manner so that Tecplot can make concurrent requests to load (and/or unload) multiple face mappings. The easiest way to write thread-safe callbacks is not to use any shared state (i.e. global or static state) in order to perform the requested action but instead to use private client data to maintain all the information needed to perform the requested action.

Calls made back to Tecplot in response to a load, unload, or cleanup request should be limited to queries except in the case where data is being loaded into a face mapping. In addition, no state changes should be broadcast by the callbacks.

The method for loading and accessing face map data with custom load-on-demand is similar to custom load-on-demand for field data (see ADK Users Manual for details): The add-on supplied LoadCallback() callback is responsible for loading the entire face map data into the Tecplot prepared face map backing. Tecplot is responsible for allocating and freeing the space for the face map backing. In addition, the add-on must supply the CleanupCallback() callback to receive notification of when the face map is no longer needed. Optionally, the add-on may supply the UnloadCallback() callback to receive notification of when the face map is being unloaded. Most add-ons should supply NULL for the UnloadCallback() callback, instructing Tecplot to assume responsibility for unloading the face map and re-loading it in an efficient form.

Note:
If using deferred assignment by calling TecUtilDataFaceMapAssignElemToNodeMap(), then NumFaces and NumFaceNodes should both be 0 since the number of unique faces and the number of faces nodes for them is determined by Tecplot.
Since:
11.2-1-0
Parameters:
Zone Zone for which the face map will now be custom load-on-demand.
NumFaces Total number of unique faces.
NumFaceNodes Total number of nodes for all faces. This is not the number of unique nodes but the total number. For example if a face map defined two triangles polygons that share a common face, NumFaces would be 5 and NumFaceNodes would be 6, not 4.
NumFaceBndryFaces Total number of faces boundary faces.
NumFaceBndryConns Total number of boundary connected elements or element/zone pairs.
LoadCallback Tecplot calls this callback when the face map is to be loaded. The LoadCallback() callback may never get called if the face map is not needed or it may get called immediately if load-on-demand capabilities are not available. This callback is called asynchronously.
UnloadCallback Add-ons can supply NULL for this callback. Supplying NULL instructs Tecplot to handle the unloading (and subsequent reloading) of the face map without the intervention of the add-on, however Tecplot will be forced to write the data to its temporary directory when unloaded thereby incurring additional I/O expense. If the add-on does supply this callback, Tecplot calls it when the face map is to be unloaded. This query provides the add-on an opportunity to allow or deny a face map to be unloaded by returning TRUE or FALSE respectively. Unless there is a compelling reason, such as very expensive load costs (in which case NULL should probably be supplied for this callback), the add-on should honor Tecplot's request to unload the face map (i.e. the UnloadCallback() callback should return TRUE). An add-on may also cleanup any private resources that are not needed when the face map is unloaded, however the add-on must still maintain enough information to load the face map again if requested by Tecplot. The UnloadCallback() callback may never get called if the face map does not need to be unloaded nor will the UnloadCallback() callback necessarily be called before the CleanupCallback() callback. This callback is called asynchronously.
CleanupCallback Tecplot calls this callback when the face map is to be cleaned up. This allows the add-on to cleanup any private resources that were used in conjunction with identifying or loading this face map. After a face map is cleaned up Tecplot will never again request it to be loaded. Tecplot may or may not call the UnloadCallback() callback before calling the CleanupCallback() callback. Additionally, the CleanupCallback() callback will be called even if the face map was never loaded. This callback is called asynchronously.
ClientData Private client data needed by the custom load-on-demand callbacks to perform the duties of loading, unloading, and cleaning up the face map. Tecplot stores the client data in the face map structure and must be retrieved by the callbacks using TecUtilDataFaceMapGetClientData(). The client data should ONLY be retrieved in response to a custom load, unload, or cleanup callback. At no other time is the request valid.
Returns:
TRUE if successful, FALSE otherwise.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Following is an example of how to create a face map using the Custom Load on Demand. 
   typedef struct
     {
       char      *DataFileName;
       long       SeekOffset;
       ... other information needed to load face map data
     } MyFaceMapClientData_s;

   Boolean_t MyFaceMapLoader(FaceMap_pa FaceMap)
   {
     REQUIRE(VALID_REF(FaceMap));

     MyFaceMapClientData_s *MyClientData = (MyFaceMapClientData_s *)TecUtilDataFaceMapGetClientData(FaceMap);

     // open the data file
     FILE *MyDataFile = fopen(MyClientData->DataFileName, "rb");
     Boolean_t IsOk = (MyDataFile != NULL);

     // seek to the place in the file where the face map data is located
     IsOk = IsOk && (fseek(MyDataFile, MyClientData->SeekOffset, SEEK_SET) == 0);
     if (IsOk)
       {
         // load the data into the zone's face map
         IsOk = ReadMyFaceMapDataIntoZone(MyDataFile, MyClientData, FaceMap);
       }

     // cleanup
     if (MyDataFile != NULL)
       fclose(MyDataFile);

     ENSURE(VALID_BOOLEAN(IsOk));
     return IsOk;
   }

   Boolean_t MyFaceMapUnload(FaceMap_pa FaceMap)
   {
     REQUIRE(VALID_REF(FaceMap));

     // We don't have any private data to cleanup (i.e. in addition to the
     // private client data which we don't cleanup here) so all we have to do
     // is return TRUE or FALSE letting Tecplot know that it can or can not
     // unload the face map.
     Boolean_t Result = TRUE; // ...tell Tecplot to go ahead and unload the face map

     ENSURE(VALID_BOOLEAN(Result));
     return Result;
   }

   void MyFaceMapCleanup(FaceMap_pa FaceMap)
   {
     REQUIRE(VALID_REF(FaceMap));

     MyFaceMapClientData_s *MyClientData = (MyFaceMapClientData_s *)TecUtilDataFaceMapGetClientData(FaceMap);

     // cleanup privately allocated resources
     free(MyClientData->DataFileName);
     free(MyClientData);
   }

   .
   .
   .
   LgIndex_t NumFaces          = ... // number of unique faces
   LgIndex_t NumFaceNodes      = ... // total number of face nodes
   LgIndex_t NumFaceBndryFaces = ... // total number of boundary faces
   LgIndex_t NumFaceBndryConns = ... // total number of boundary face Connections
   MyFaceMapClientData_s *MyClientData = (MyFaceMapClientData_s *)malloc(sizeof(MyFaceMapClientData_s));
   const char *MyDataFileName = "MyDataFileName.dat";
   MyClientData->MyDataFileName = (char *)malloc(strlen(MyDataFileName)+1);
   strcpy(MyClientData->MyDataFileName, MyDataFileName);
   MyClientData->SeekOffset = ... determined somewhere else
   ... initialize any other client data information needed to load face map data
   IsOk = TecUtilDataFaceMapCustomLOD(3,
                                      NumFaces,
                                      NumFaceNodes,
                                      NumFaceBndryFaces,
                                      NumFaceBndryConns,
                                      MyFaceMapLoader,
                                      MyFaceMapUnload, // most add-ons should pass NULL instead of MyFaceMapUnload
                                      MyFaceMapCleanup,
                                      (ArbParam_t)MyClientData);

Python Syntax:

    This function is not supported in Python.

See also:
TecUtilDataFaceMapAlloc(), TecUtilDataConnectShare(), TecUtilDataFaceMapBeginAssign(), TecUtilDataFaceMapAssignNodes(), TecUtilDataFaceMapAssignZones(), TecUtilDataFaceMapEndAssign(), TecUtilDataFaceMapAssignElemToNodeMap(), TecUtilMemoryChangeNotify()

Boolean_t TecUtilDataFaceMapEndAssign ( FaceMap_pa  FaceMap  ) 

Ends a face-mapping assignment sequence.

All face nodes and elements must be delivered between the face map begin/end assignment clause.

This function is Thread Safe.

Note:
This function should not be called in response to a custom face map load callback. For custom face map load callbacks Tecplot is responsible for allocating the face map, beginning an assignment context and ending it after the loader callback returns. The callback only need deliver face map information to Tecplot with calls to TecUtilDataFaceMapAssignBConns(), TecUtilDataFaceMapAssignElems(), TecUtilDataFaceMapAssignNodes() or TecUtilDataFaceMapAssignElemToNodeMap().
Since:
11.2-1-0
Parameters:
FaceMap An open face-mapping assignment context to which the face nodes and elements were assigned.
Returns:
TRUE if all face nodes and elements were supplied and the supplied face nodes and left and right elements are within the range of the zone structure, FALSE otherwise.
Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapEndAssign (
   &           FaceMapPtr)
    POINTER   (FaceMapPtr, FaceMap)

Python Syntax:

  Results = TecUtil.DataFaceMapEndAssign(FaceMap)

  Input:
                  FaceMap              opaque pointer
  Output:
    Results[0]    ReturnVal            boolean

void TecUtilDataFaceMapGetBndryConn ( FaceMap_pa  FaceMap,
LgIndex_t  Face,
LgIndex_t  BndryConnOffset,
LgIndex_t *  BndryElem,
EntIndex_t *  BndryElemZone 
)

Fetch a connected element and its zone for a boundary face.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap Face mapping.
Face The boundary face for which the connected element is desired.
BndryConnOffset The boundary connection offset for the element. This must be between 1 and the number of boundary elements returned by TecUtilDataFaceMapGetNBndryConns.
BndryElem The desired connected element. A returned element number of TECUTIL_NO_NEIGHBORING_ELEM indicates no neighboring element. If this is the only boundary connection for the face, then the boundary face has no neighboring elements. If there are more boundary connections for this boundary face, then the boundary face is partially obscured, and the remaining boundary connections for the face will list the elements and zones that partially obscure the face.
BndryElemZone The desired connected zone. A returned zone number of TECUTIL_NO_NEIGHBORING_ZONE indicates a self reference (in other words, the zone associated with the face mapping).
Precondition:
FaceMap Pointer must be a valid address and non-NULL.

BndryElem Pointer must be a valid address and non-NULL.

BndryElemZone Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapGetBndryConn (
   &           FaceMapPtr,
   &           Face,
   &           BndryConnOffset,
   &           BndryElem,
   &           BndryElemZone)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 Face
    INTEGER*4 BndryConnOffset
    INTEGER*4 BndryElem
    INTEGER*4 BndryElemZone

Python Syntax:

  Results = TecUtil.DataFaceMapGetBndryConn(FaceMap, Face, BndryConnOffset)

  Input:
                  FaceMap              opaque pointer
                  Face                 int
                  BndryConnOffset      int
  Output:
    Results[0]    BndryElem            int
    Results[1]    BndryElemZone        int

ArbParam_t TecUtilDataFaceMapGetClientData ( FaceMap_pa  FaceMap  ) 

Return the custom load-on-demand client data from a face map handle.

The client data should ONLY be retrieved in response to a custom load, unload, or cleanup callback. At no other time is the request valid. This function is Thread Safe.

Parameters:
FaceMap Custom load-on-demand face map handle.
Returns:
Client data for the custom load-on-demand add-on.
Python Syntax:
    This function is not supported in Python.


     Boolean_t MyFaceMapLoader(FaceMap_pa FaceMap)
     {
       Boolean_t Result;
       MyClientData_s *MyClientData = (MyClientData_s *)TecUtilDataFaceMapGetClientData(FaceMap);

       // load the custom face map using client data
       .
       .
       .

     return Result;
   }

See also:
TecUtilDataFaceMapCustomLOD()

LgIndex_t TecUtilDataFaceMapGetFaceNode ( FaceMap_pa  FaceMap,
LgIndex_t  Face,
LgIndex_t  NodeOffset 
)

Fetch a node from the face.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap Face mapping.
Face The face for which the node is desired.
NodeOffset The node offset within the face.
Returns:
The desired node.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapGetFaceNode (
   &          FaceMapPtr,
   &          Face,
   &          NodeOffset)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 Face
    INTEGER*4 NodeOffset

Python Syntax:

  Results = TecUtil.DataFaceMapGetFaceNode(FaceMap, Face, NodeOffset)

  Input:
                  FaceMap              opaque pointer
                  Face                 int
                  NodeOffset           int
  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilDataFaceMapGetLeftElem ( FaceMap_pa  FaceMap,
LgIndex_t  Face 
)

The left element associated with the specified face.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap Face mapping.
Face The face for which the left element is desired.
Returns:
Left element number, TECUTIL_NO_NEIGHBORING_ELEM if there is no neighbor, or TECUTIL_BOUNDARY_FACE indicating that this is a boundary face. Further information about a boundary face may be gathered. See TecUtilDataFaceMapGetNBndryConns for more details.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapGetLeftElem (
   &          FaceMapPtr,
   &          Face)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 Face

Python Syntax:

  Results = TecUtil.DataFaceMapGetLeftElem(FaceMap, Face)

  Input:
                  FaceMap              opaque pointer
                  Face                 int
  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilDataFaceMapGetNBndryConns ( FaceMap_pa  FaceMap,
LgIndex_t  Face 
)

Retrieves the number of boundary connections for the specified face.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap Face mapping.
Face The face for which the number of connections is desired.
Returns:
The number of boundary connections for the face.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapGetNBndryConns (
   &          FaceMapPtr,
   &          Face)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 Face

Python Syntax:

  Results = TecUtil.DataFaceMapGetNBndryConns(FaceMap, Face)

  Input:
                  FaceMap              opaque pointer
                  Face                 int
  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilDataFaceMapGetNFaceNodes ( FaceMap_pa  FaceMap,
LgIndex_t  Face 
)

Indicates how many nodes comprise the specified face.

Always returns 2 for polygonal zones.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap Face mapping.
Face The face for which the number of nodes is desired.
Returns:
Number of face nodes.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapGetNFaceNodes (
   &          FaceMapPtr,
   &          Face)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 Face

Python Syntax:

  Results = TecUtil.DataFaceMapGetNFaceNodes(FaceMap, Face)

  Input:
                  FaceMap              opaque pointer
                  Face                 int
  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilDataFaceMapGetNFaces ( FaceMap_pa  FaceMap  ) 

Indicates how many faces comprise the specified face mapping.

This function is Thread Safe.

Since:
11.2-1-8349
Parameters:
FaceMap Face mapping.
Returns:
Number of faces.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapGetNFaces (
   &          FaceMapPtr)
    POINTER   (FaceMapPtr, FaceMap)

Python Syntax:

  Results = TecUtil.DataFaceMapGetNFaces(FaceMap)

  Input:
                  FaceMap              opaque pointer
  Output:
    Results[0]    ReturnVal            int

FaceMap_pa TecUtilDataFaceMapGetReadableRef ( EntIndex_t  Zone  ) 

Gets a readable face mapping for the specified polyhedral or polygonal zone of the current frame.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
Zone Polyhedral or polygonal zone number.
Returns:
A readable face mapping for the specified polyhedral or polygonal zone or NULL if unsuccessful.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapGetReadableRef (
   &           Zone,
   &           FaceMapPtr)
    INTEGER*4 Zone
    POINTER   (FaceMapPtr, FaceMap)

Python Syntax:

  Results = TecUtil.DataFaceMapGetReadableRef(Zone)

  Input:
                  Zone                 int
  Output:
    Results[0]    ReturnVal            opaque pointer

LgIndex_t TecUtilDataFaceMapGetRightElem ( FaceMap_pa  FaceMap,
LgIndex_t  Face 
)

The right element associated with the specified face.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
FaceMap Face mapping.
Face The face for which the right element is desired.
Returns:
Right element number, TECUTIL_NO_NEIGHBORING_ELEM if there is no neighbor, or TECUTIL_BOUNDARY_FACE indicating that this is a boundary face. Further information about a boundary face may be gathered. See TecUtilDataFaceMapGetNBndryConns for more details.
Precondition:
FaceMap Pointer must be a valid address and non-NULL.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceMapGetRightElem (
   &          FaceMapPtr,
   &          Face)
    POINTER   (FaceMapPtr, FaceMap)
    INTEGER*4 Face

Python Syntax:

  Results = TecUtil.DataFaceMapGetRightElem(FaceMap, Face)

  Input:
                  FaceMap              opaque pointer
                  Face                 int
  Output:
    Results[0]    ReturnVal            int

FaceMap_pa TecUtilDataFaceMapGetWritableRef ( EntIndex_t  Zone  ) 

Gets a writable face mapping for the specified polyhedral or polygonal zone of the current frame.

If the current face mapping for the zone is not writable, the current face mapping will be replaced with a writable copy. If the original face mapping was shared with other zones, the writable copy will be shared with the same zones.

This function is Thread Safe.

Since:
11.2-1-0
Parameters:
Zone Polyhedral or polygonal zone number.
Returns:
A writable face mapping for the specified polyhedral or polygonal zone or NULL if unsuccessful.
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    SUBROUTINE TecUtilDataFaceMapGetWritableRef (
   &           Zone,
   &           FaceMapPtr)
    INTEGER*4 Zone
    POINTER   (FaceMapPtr, FaceMap)

Python Syntax:

  Results = TecUtil.DataFaceMapGetWritableRef(Zone)

  Input:
                  Zone                 int
  Output:
    Results[0]    ReturnVal            opaque pointer

Generated on Tue Mar 12 02:24:43 2013 for Tecplot by  doxygen 1.5.5