NAME
          DtCnetGetStateTable - Get the state table for the specified
          character.

     SYNOPSIS
          #include <Dt.h>

          int  DtCnetGetStateTable( int cnetID, DtStateTable **table )

     DESCRIPTION
          DtCnetGetStateTable() returns the state table of the
          MetaCycle character denoted by cnetID, via the pointer to
          the table parameter.

          The structures for accessing the MetaCycle state table are
          declared in Dt.h as follows:

          typedef int DtStateTableEntry;

          typedef struct {
               int    storage;
               int    length;
               int    nextNode;
               int    entryFrame;
               char   *data1;
               char   *data2;
               char   *data3;
               char   *data4;
          } DtTransition;

          typedef struct {
               int    flags;
               int    storage;
               int    length;
               char   *data1;
               char   *data2;
               char   *data3;
               char   *data4;
          } DtSnippet;

          typedef struct {
               int                 nodes;
               int                 arcs;
               DtStateTableEntry   *adjacency;
               DtTransition        *arcData;
               DtSnippet           *nodeData;
               char                *data1;
               char                *data2;
               char                *data3;
               char                *data4;
          } DtStateTable;

          The state table returned by DtCnetGetStateTable() does not
          contain any animation data itself. It contains references to
          the animation stored separately in the model. The table
          references the animation by frame number. The MetaCycle
          animation is written as it is generated to a single list of
          frames.  Currently all the snippets are output with the
          transitions following, though this need not always be the
          case. It is important to deallocate storage used for the
          table when finished.

          A DtSnippet structure is created for each snippet in the
          MetaCycle window. The flags field is currently unused. The
          storage field contains the frame number of the first frame
          of animation for this snippet. The length field contains the
          number of frames in the snippet. The last frame of the
          snippet is frame storage+length.  The data1, data2, data3,
          and data4 fields contain the strings set as Target data in
          the MetaCycle Detail window in Alias.

          There is a DtTransition structure for each actual transition
          in the MetaCycle window. Transitions with rolling start or
          end points are converted into several transitions in the
          state table, one for each start and end point.  A transition
          contains storage and length fields similar to those found in
          a snippet. The nextNode field holds the integer ID of the
          snippet destination of a transition. The entryFrame field
          contains the first frame of the snippet to display when the
          transition is completed. The entryFrame of a transition need
          not be identical to the storage field of the nextNode
          snippet; transitions can force entry into snippets at any
          point in the snippet's duration. The data1, data2, data3,
          and data4 fields contain the strings set as Target data in
          the MetaCycle Detail window in Alias. These are used in the
          demonstration character engines to denote which keypad
          button activates a particular transition, though they could
          have many other uses.

          The DtStateTable structure returned to the user by
          DtCnetGetStateTable() contains fields containing the number
          of snippets (nodes) and transitions (arcs) in the state
          table. The transitions are kept as an array of DtTransition
          structures pointed to by the arcData field of the state
          table. The snippets are kept as an array of DtSnippet
          structures pointed to by the nodeData field of the state
          table.  The adjacency field points to an array of
          DtStateTableEntry objects. This array contains nodes*arcs
          elements, with the first arcs elements corresponding to
          connectivity information for the first snippet and the
          second arcs elements having the same information for the
          second snippet. For the snippet identified as N, the
          adjacency information will be found at adjacency[N*arcs].
          (Snippets are numbered from 0 to nodes-1.)  Adjacency data
          for a snippet is a list of DtStateTableEntry objects nodes
          elements long. For each transition i, adjacency[ N*arcs+i ]
          contains the frame number at which the engine can move from
          the snippet N to the transition i.  If this value is
          negative, there is no connection between the node and the
          snippet.


     IMPLEMENTATION NOTES
          The character network tools are only implemented in the
          AliasAPI implementation of Dt. The state table will only
          contain valid data after the MetaCycle has been run. Calling
          DtCnetGetStateTable() under OpenModel or under OpenAlias
          without having run the network (in record mode) first will
          generate invalid data.

          User should delete the table and its contents themselves.

     DIAGNOSTICS
          DtCnetGetStateTable() returns one on success and zero on
          failure.


     FILES
          Link with -lDtOMio