home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / narrator.doc < prev    next >
Text File  |  1992-09-01  |  13KB  |  436 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. narrator.device/AbortIO
  6. narrator.device/OpenDevice
  7. narrator.device/CMD_FLUSH
  8. narrator.device/CMD_READ
  9. narrator.device/CMD_RESET
  10. narrator.device/CMD_START
  11. narrator.device/CMD_STOP
  12. narrator.device/CMD_WRITE
  13. narrator.device/CloseDevice
  14.  
  15.  
  16. narrator.device/AbortIO                    narrator.device/AbortIO
  17.  
  18.    NAME
  19.     AbortIO - Abort an IO request
  20.  
  21.  
  22.    SYNOPSIS
  23.     AbortIO(IORequest)
  24.            A1
  25.  
  26.  
  27.    FUNCTION
  28.     Exec library call to abort a specified READ or WRITE request.
  29.     The IORequest may be in the queue or currently active.  If
  30.     currently active, the request is immediately stopped and then
  31.     removed.
  32.  
  33.  
  34.    INPUTS
  35.     Pointer to the IORequest block to be aborted.
  36.  
  37.  
  38.    RESULTS
  39.     io_Error field in the IORequest block set to #IOERR_ABORTED.
  40.  
  41.  
  42.    SEE ALSO
  43.  
  44.  
  45.  
  46. narrator.device/CloseDevice              narrator.device/CloseDevice
  47.  
  48.    NAME
  49.     CloseDevice - terminates access to the narrator device
  50.  
  51.  
  52.    SYNOPSIS
  53.     CloseDevice(IORequest)
  54.                A1
  55.  
  56.    FUNCTION
  57.     Close invalidates the IO_UNIT and IO_DEVICE fields in the
  58.     IORequest block, preventing subsequent IO until another
  59.     OpenDevice.  CloseDevice also reduces the open count.  If 
  60.     the count goes to 0 and the expunge bit is set, the device
  61.     is expunged.  If the open count goes to zero and the delayed
  62.     expunge bit is not set, CloseDevice sets the expunge bit.
  63.  
  64.  
  65.    INPUTS
  66.     A valid IORequest block with its io_Message structure, and
  67.     io_Device and io_Unit fields properly initialized.  These
  68.     fields are initialized by OpenDevice.
  69.  
  70.  
  71.    RESULTS
  72.     CloseDevice invalidates the unit and device pointers in the
  73.     IORequest block.
  74.  
  75.  
  76.    SEE ALSO
  77.  
  78.  
  79.  
  80. narrator.device/CMD_FLUSH            narrator.device/CMD_FLUSH
  81.  
  82.    NAME
  83.     CMD_FLUSH - Aborts all inprogress and queued requests
  84.  
  85.  
  86.    SYNOPSIS
  87.     Standard device command.
  88.  
  89.  
  90.    FUNCTION
  91.     Aborts all inprogress and queued speech requests.
  92.  
  93.  
  94.    INPUTS
  95.     Valid IORequest block with the io_Command field set to CMD_FLUSH.
  96.     A valid IORequest block is one with its io_Message structure, and
  97.     io_Device and io_Unit fields properly initialized.  The easiest 
  98.     way to insure proper initialization is to make a copy of the
  99.     IORequest block after a successful OpenDevice call.
  100.  
  101.  
  102.    RESULTS
  103.     io_Error in IORequest block set to 0
  104.  
  105.  
  106.    SEE ALSO
  107.       Exec input/output documentation.
  108.  
  109.  
  110. narrator.device/CMD_Read            narrator.device/CMD_Read
  111.  
  112.    NAME
  113.     CMD_READ - Query the narrator device for mouth shape or other
  114.            synchronization events.
  115.  
  116.  
  117.    SYNOPSIS
  118.     Standard device command.
  119.  
  120.  
  121.    FUNCTION
  122.     Currently, there are three events which the user can inquire
  123.     about from the narrator device.  These are: mouth shape changes,
  124.     start of word, and start of syllable.  Each read request returns
  125.     information about any or all of these events as determined by
  126.     the bits set in the sync field of the read IORequest block.  In
  127.     the case of mouth shape changes, each shape returned is guaranteed
  128.     to be different from the previously returned shape to allow
  129.     updating to be done only when necessary.  Each read request is 
  130.     associated with a write request    by information contained in the 
  131.     IORequest block used to open the device.  Since the first field
  132.     in the read IORequest block is a write IORequest structure, this 
  133.     association is easily made by copying the write IORequest block 
  134.     (after the OpenDevice call) into the voice field of the read 
  135.     IORequest block.  If there is no write in progress or in the
  136.     device input queue with the same pseudo unit number as the read
  137.     request, the read will be returned to the user with an error.  This
  138.     is also how the user knows that the write request has finished and
  139.     that s/he should not issue any more reads.  Note that in this case
  140.     the mouth shapes may not be different from previously returned values.
  141.  
  142.  
  143.    INPUTS
  144.     mouth_rb IORequest block with the voice field (a narrator_rb 
  145.     structure) copied from the associated write request with the 
  146.     following fields modified:
  147.  
  148.        io_Message - Pointer to message port for read request
  149.        io_Command - CMD_READ
  150.        io_Error   - Clear before issuing first read
  151.        width      - 0
  152.        height     - 0
  153.  
  154.  
  155.    RESULTS
  156.     As long as the speech is in progress, each read returns the
  157.     following information in the mouth_rb IORequest block.
  158.  
  159.     If mouth shape changes are requested the following fields are
  160.     modified:
  161.        width  - Contains mouth width value in arbitrary units
  162.        height - Contains mouth height value in arbitrary units
  163.        shape  - Compressed form of mouth shapes (internal use only)
  164.  
  165.  
  166.     ******    NEW FOR V37 NARRATOR
  167.  
  168.     If word synchronization is requested:
  169.        sync   - Bit NDB_WORDSYNC is set
  170.  
  171.     If syllable synchronization is requested:
  172.        sync   - Bit NDB_SYLSYNC is set
  173.  
  174.     Note that any or all of the above fields can be set and it is
  175.     the user's responsibility to check for all possibilities.
  176.  
  177.  
  178.    SEE ALSO
  179.     CMD_WRITE
  180.     Exec input/output documentation.
  181.  
  182.  
  183. narrator.device/CMD_RESET                narrator.device/CMD_RESET
  184.  
  185.    NAME
  186.     CMD_RESET - Reset the device to a known state
  187.  
  188.  
  189.    SYNOPSIS
  190.     Standard device command.
  191.  
  192.  
  193.    FUNCTION
  194.     Resets the device as though it has just be initialized.
  195.     Aborts all read/write requests whether active of enqueued.
  196.     Restarts device if it has been stopped.
  197.  
  198.  
  199.    INPUTS
  200.     Valid IORequest block with the io_Command field set to CMD_RESET.
  201.     A valid IORequest block is one with its io_Message structure, and
  202.     io_Device and io_Unit fields properly initialized.  The easiest 
  203.     way to insure proper initialization is to make a copy of the
  204.     IORequest block after a successful OpenDevice call.
  205.  
  206.  
  207.    RESULTS
  208.  
  209.  
  210.    SEE ALSO
  211.     Exec input/output documentation.
  212.  
  213.  
  214.  
  215.  
  216. narrator.device/CMD_START                narrator.device/CMD_START
  217.  
  218.  
  219.    NAME
  220.     CMD_START - Restarts the device after a CMD_STOP command
  221.  
  222.  
  223.    SYNOPSIS
  224.     Standard device command.
  225.  
  226.  
  227.    FUNCTION
  228.     CMD_START restarts the currently active speech (if any)    and 
  229.     allows queued requests to start.
  230.  
  231.  
  232.    INPUTS
  233.     Valid IORequest block with the io_Command field set to CMD_START
  234.     A valid IORequest block is one with its io_Message structure, and
  235.     io_Device and io_Unit fields properly initialized.  The easiest 
  236.     way to insure proper initialization is to make a copy of the
  237.     IORequest block after a successful OpenDevice call.
  238.  
  239.  
  240.    RESULTS
  241.     io_Error set to 0.
  242.  
  243.  
  244.    SEE ALSO
  245.     Exec input/output documentation.
  246.  
  247.  
  248.  
  249.  
  250. narrator.device/CMD_STOP                narrator.device/CMD_STOP
  251.  
  252.    NAME
  253.     CMD_STOP  - Stops the device.
  254.  
  255.  
  256.    SYNOPSIS
  257.     Standard device command.
  258.  
  259.  
  260.    FUNCTION
  261.     CMD_STOP halts the currently active speech (if any) and    prevents
  262.     any queued requests from starting. 
  263.  
  264.  
  265.    INPUTS
  266.     Valid IORequest block with the io_Command field set to CMD_STOP.
  267.     A valid IORequest block is one with its io_Message structure, and
  268.     io_Device and io_Unit fields properly initialized.  The easiest 
  269.     way to insure proper initialization is to make a copy of the
  270.     IORequest block after a successful OpenDevice call.
  271.  
  272.  
  273.    RESULTS
  274.     io_Error set to 0.
  275.  
  276.  
  277.    SEE ALSO
  278.     Exec input/output documentation.
  279.  
  280.  
  281. narrator.device/CMD_WRITE                narrator.device/CMD_WRITE
  282.  
  283.    NAME
  284.     CMD_WRITE - Send speech request to the narrator device
  285.  
  286.  
  287.    SYNOPSIS
  288.     Standard device command.
  289.  
  290.  
  291.    FUNCTION
  292.     Sends a phonetic string to the narrator device to be spoken
  293.     and, optionally, is used to direct the narrator device to 
  294.     return mouth shape changes, and word and syllable sync events
  295.     in response to read requests from the user.  The phonetic string
  296.     consists of ASCII characters representing the individual phonemes.
  297.     Refer to the narrator device chapter of the libraries and devices
  298.     volume of the ROM Kernel Manual for detailed information.
  299.  
  300.     
  301.    INPUTS
  302.     User IORequest block (struct narrator_rb as defined in .h file).
  303.     The OpenDevice call will initialize the IORequest block to a 
  304.     "standard male" voice.  If you want to change any parms, do so
  305.     after the OpenDevice call and before the DoIO (or SendIO/WaitIO).
  306.     For a complete description of the narrator_rb structure, see the
  307.     narrator.h or .i include file.  Note that the OpenDevice call does
  308.     not initialize all the fields needed by the narrator device.  The
  309.     IORequest fields which must be set by the user before issuing the
  310.     write request are:
  311.  
  312.        io_Command - Set to CMD_WRITE
  313.        io_Data    - Pointer to phonetic string
  314.        io_Length  - Length of phonetic string
  315.        ch_masks   - Array of audio channel selection masks (see audio
  316.             device documentation for description of this field)
  317.        nm_masks   - Number of audio channel selection masks
  318.  
  319.        ****** NEW FOR V37 NARRATOR
  320.  
  321.        flags - The bit NDB_NEWIORB must be set in the flags field if
  322.            any of the new features of the V37 narrator are used
  323.  
  324.  
  325.     In addition to producing synthetic speech, the narrator device
  326.     also provides features for synchronizing the speech to animation
  327.     or other user defined events.  There are three types of events
  328.     that the user can request.  They are mouth shape changes, start of
  329.     new word, and start of new syllable.  Mouth shape changes are 
  330.     requested by setting the mouths field of the IORequest block to a
  331.     non-zero value.  Word and syllable sync events are requested by 
  332.     setting the NDB_WORDSYNC and/or NDB_SYLSYNC bits in the flags field
  333.     of the IORequest block.  Note that word and syllable sync only work
  334.     in V37 and later versions of the narrator device.
  335.  
  336.  
  337.    RESULTS
  338.     The narrator device range checks and performs other validity
  339.     checks for all input parms.  If any input is in error, the device
  340.     sets the io_Error field of the IORequest block to an appropriate
  341.     value (see include files for error codes).  If everything is in
  342.     order, the narrator device will produce the speech and clear the
  343.     io_Error field.  The io_Actual field is set to the length of the
  344.     input string that was actually processed.  If the return code
  345.     indicates a phoneme error (ND_PhonErr), io_Actual is the NEGATIVE
  346.     of the position in the input string where the error occured.
  347.  
  348.  
  349.    SEE ALSO
  350.     Read command.
  351.     Audio device documentation.
  352.     Exec input/output documentation.
  353.  
  354.  
  355. narrator.device/OpenDevice                narrator.device/OpenDevice
  356.  
  357.    NAME
  358.     OpenDevice - opens the narrator device.
  359.  
  360.  
  361.    SYNOPSIS
  362.     error = OpenDevice("narrator.device",  unit, IORequest, flags);
  363.      D0                       A0            D0     A1         D1
  364.  
  365.  
  366.    FUNCTION
  367.     The OpenDevice routine grants access to the narrator device.
  368.     OpenDevice checks the unit number, and if non-zero, returns an
  369.     error (ND_UnitErr).  If this is the first time the driver has
  370.     been opened, OpenDevice will attempt to open the audio device
  371.     and allocate the driver's static buffers.  If either of these
  372.     operations fail, an error is returned.  See the .h and .i
  373.     include files for possible error return codes.  Next, OpenDevice
  374.     (done for all opens, not just the first one) initializes various
  375.     fields in the user's IORequest block (see below).  If users wish
  376.     to use non-default values for these parms, the values must be set
  377.     after the open is done.  OpenDevice also assigns a pseudo unit
  378.     number to the IORB for use in synchronizing read and write requests.
  379.     See the read command for more details.    Finally, OpenDevice stores
  380.     the device node pointer in the IORequest block and clears the
  381.     delayed expunge bit.
  382.  
  383.     ***** NEW FOR V37 NARRATOR *****
  384.  
  385.     Several new fields in the IORequest block have been added for V37
  386.     narrator.  These fields are initialized when the device is opened
  387.     if the NDB_NEWIORB bit is set in the flags field of the user's 
  388.     IORequest block.  Note that NDB_NEWIORB is set in the IORequest
  389.     block, NOT in the "flags" input parm to the OpenDevice call.
  390.  
  391.  
  392.    INPUTS
  393.     device     - "narrator.device"
  394.     unit       - 0
  395.     IORequest  - Pointer to the user's IORequest block
  396.     flags       - 0
  397.  
  398.  
  399.    RESULTS
  400.     The narrator device will initialize the IORequest block as follows
  401.     (assume IORB points to the IOrequest block):
  402.  
  403.     IORB->rate = 150;        /* Speaking rate in words/minute */
  404.     IORB->pitch = 110;        /* Baseline pitch in Hertz         */
  405.     IORB->mode = NATURALF0;        /* Pitch (F0) mode        */
  406.     IORB->sex = MALE;        /* Sex of voice            */
  407.     IORB->volume = 64        /* Volume, full on        */
  408.     IORB->sampfreq = 22200        /* Audio sampling freq         */
  409.     IORB->mouths = 0        /* Don't generate sync events    */
  410.  
  411.     and if the NDB_NEWIORB bit is set:
  412.  
  413.     IORB->F0enthusiasm = 0        /* F0 excursion factor        */
  414.     IORB->F0perturb = 32        /* F0 perturbation (in 32nds)    */
  415.     IORB->F1adj = 0            /* F1 adjustment in ±5% steps    */
  416.     IORB->F2adj = 0         /* F2 adjustment in ±5% steps    */
  417.     IORB->F3adj = 0            /* F3 adjustment in ±5% steps    */
  418.     IORB->A1adj = 0            /* A1 adjustment in decibels    */
  419.     IORB->A2adj = 0            /* A2 adjustment in decibels    */
  420.     IORB->A3adj = 0             /* A3 adjustment in decibels    */
  421.     IORB->articulate = 100        /* Transition time multiplier    */
  422.     IORB->centralize = 0        /* Degree of vowel centralization */
  423.     IORB->centphon = ""        /* Pointer to central ASCII phon  */
  424.     IORB->AVbias = 0        /* AV bias            */
  425.     IORB->AFbias = 0        /* AF bias            */
  426.     IORB->priority = 100        /* Priority while speaking    */
  427.  
  428.  
  429.  
  430.    SEE ALSO
  431.     The include files contain the complete IORequest block definition,
  432.         default settings, and error return codes.
  433.     Exec input/output documentation.
  434.  
  435.  
  436.