@database "narrator"
@master "ADCD_v1.2:IncludesD/Inc&AD1.3/doc/narrator.doc"

@Node Main "narrator.doc"
@TOC 1.3Includes_Autodocs/Autodocs

@{" AbortIO() " Link "AbortIO()"}        @{" CMD_READ " Link "CMD_READ"}     @{" CMD_STOP " Link "CMD_STOP"}
@{" CloseDevice() " Link "CloseDevice()"}    @{" CMD_RESET " Link "CMD_RESET"}    @{" CMD_WRITE " Link "CMD_WRITE"}
@{" CMD_FLUSH " Link "CMD_FLUSH"}        @{" CMD_START " Link "CMD_START"}    @{" OpenDevice() " Link "OpenDevice()"}

@EndNode

@Node "AbortIO()" "narrator.device/AbortIO"

NAME
    AbortIO - Abort an IO request

SYNOPSIS
    AbortIO(iORequest)
                A1

FUNCTION
    Aborts a speech IO request.  The request may be in the queue
    or currently active.

INPUTS
    iORequest - pointer to the @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block of request to abort.

RESULTS
    io_Error field of @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} set to IOERR_ABORTED

BUGS

SEE ALSO
    @{"narrator.device/BeginIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/serial/BeginIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CloseDevice()" "narrator.device/CloseDevice"

NAME
    CloseDevice - terminates access to the narrator device

SYNOPSIS
    CloseDevice(iORequest)
                    A1

FUNCTION
    Close invalidates the io_Unit and io_Device fields in the
    @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17}, preventing subsequent IO until another @{"OpenDevice" Link "OpenDevice()"}.
    CloseDevice also reduces the open count.  If the count
    goes to 0 and the expunge bit is set, the device is
    expunged.  If the open count goes to zero and the delayed
    expunge bit is not set, CloseDevice sets the expunge bit.

INPUTS
    iORequest- pointer to an @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block

RESULTS
    The unit and device pointers of the @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block are invalidated.

BUGS

SEE ALSO
    @{"narrator.device/OpenDevice" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/serial/OpenDevice()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CMD_FLUSH" "narrator.device/CMD_FLUSH"

NAME
    CMD_FLUSH - Aborts all inprogress and queued requests

FUNCTION
    Aborts all in-progress and queued speech requests.

IO REQUEST
    io_Device       set by @{"OpenDevice" Link "OpenDevice()"}
    io_Unit         set by @{"OpenDevice" Link "OpenDevice()"}
    io_Command      CMD_FLUSH

RESULTS
    io_Error        always cleared

BUGS

SEE ALSO
    @{"exec.library/SendIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/SendIO()"}, @{"exec.library/DoIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/DoIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CMD_READ" "narrator.device/CMD_READ"

NAME
    CMD_READ - Return the next different mouth shape from an
           associated write.

FUNCTION
    The read command of the narrator device returns mouth
    shapes to the user.  The shape returned is guaranteed
    to be differnt from the previously returned shape
    (allowing updating to be done only when something has
    changed).  Each read request is associated with a
    write request by the pseudo-unit number assigned by
    the @{"OpenDevice" Link "OpenDevice()"} call.  Since the first structure in
    the read-mouth @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block (IORB) is a narrator
    (write) IORB, this association is easily made by copying
    the narrator IORB into the narrate_rb field fo the read IORB.
    See the .h,i files.  If there is no write in progress
    or in the device input queue with the same pseudo-unit
    number as the read request, the read will be
    returned to the user with an error.  This is also
    how the user knows that the write request has
    finished and that s/he should not issue any more
    reads.  Note that in this case the mouth shapes may
    not be different from previously returned values.

IO REQUEST
    with the @{"narrator_rb" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/narrator.h/Main" 66} structure copied from the
    associated write request except for:
        io_Message  - message port for read request
        io_Command  - CMD_READ
        io_Error    - 0
        width       - 0
        height      - 0

RESULTS
    @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block fields set:
        width  - mouth width in millimeters/3.67
                 (division done for scaling)
        height - mouth height in millimeters
        shape  - compressed form of mouth shapes
                 (internal use only)

BUGS

SEE ALSO
    @{"narrator.device/CMD_WRITE" Link "CMD_WRITE"},
    @{"exec.library/DoIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/DoIO()"}, @{"exec.library/SendIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/SendIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CMD_RESET" "narrator.device/CMD_RESET"

NAME
    CMD_RESET - @{"Reset" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/input/Reset()"} the device to a known state

FUNCTION
    Resets the device as though it has just be initialized.
    Aborts all read/write requests whether active of enqueued.
    Restarts device if it has been stopped.

IO REQUEST
    io_Device       set by @{"OpenDevice" Link "OpenDevice()"}
    io_Unit         set by @{"OpenDevice" Link "OpenDevice()"}
    io_Command      CMD_RESET

RESULTS
    io_Error        always cleared

BUGS

SEE ALSO
    @{"exec.library/SendIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/SendIO()"}, @{"exec.library/DoIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/DoIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CMD_START" "narrator.device/CMD_START"

NAME
    CMD_START - Restarts the device after @{"CMD_STOP" Link "CMD_STOP"}

FUNCTION
    CMD_START restarts the currently active speech (if any)
    and allows queued requests to start.

IO REQUEST
    io_Device       set by @{"OpenDevice" Link "OpenDevice()"}
    io_Unit         set by @{"OpenDevice" Link "OpenDevice()"}
    io_Command      CMD_START

RESULTS
    io_Error        always cleared

BUGS

SEE ALSO
    @{"exec.library/DoIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/DoIO()"}, @{"exec.library/SendIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/SendIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CMD_STOP" "narrator.device/CMD_STOP"

NAME
    CMD_STOP  - Stops the device.

FUNCTION
    CMD_STOP halts the currently active speech (if any) and
    prevents any queued requests from starting.

IO REQUEST
    io_Device       set by @{"OpenDevice" Link "OpenDevice()"}
    io_Unit         set by @{"OpenDevice" Link "OpenDevice()"}
    io_Command      CMD_STOP

RESULTS
    io_Error        always cleared

BUGS

SEE ALSO
    @{"exec.library/DoIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/DoIO()"}, @{"exec.library/SendIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/SendIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

@Node "CMD_WRITE" "narrator.device/CMD_WRITE"

NAME
    CMD_WRITE - Send speech request to the narrator device

FUNCTION
    Performs the speech request.  If there is an associated read
    request on the device input queue, write will remove it and
    return an initial mouth shape to the user.

    Note: if you are going to be doing reads,
          the mouths parameter must be set to 1.

IO REQUEST
    @{"narrator_rb" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/narrator.h/Main" 66} request block:
       ch_masks   - array of audio channel selection masks
                   (see audio device documentation for
                    description of this field)
       nm_masks   - number of audio channel selection masks
       mouths     - 0 if no mouths are desired
                    1 if mouths are to be read
       rate       - speaking rate
       pitch      - pitch
       mode       - pitch mode
                    0 if natural mode
                    1 if robotic mode
       sex        - 0 if male
                  - 1 if female
       io_Message - message port
       io_Command - CMD_WRITE
       io_Data    - input string
       io_Length  - length of input string

RESULTS
    The function sets the io_Error field of the IORB.  The
    io_Actual field is set to the length of the input string
    that was actually processed.  If the return code indicates
    a phoneme error (ND_PhonErr), io_Actual is the position in
    the input string where the error occured.

BUGS

SEE ALSO
    @{"narrator.device/CMD_READ" Link "CMD_READ"}, @{"devices/narrator.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/devices/narrator.h/Main" 0}
    @{"exec.library/DoIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/DoIO()"}, @{"exec.library/SendIO" Link "ADCD_v1.2:Inc&AD1.3/Autodocs/exec/SendIO()"}, @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}
    Audio device documentation.

@EndNode

@Node "OpenDevice()" "narrator.device/OpenDevice"

NAME
    OpenDevice - open the narrator device.

SYNOPSIS
    error = OpenDevice("narrator.device", 0 , iORequest , 0 );
    D0                  A0                D0  A1          D1

FUNCTION
    The OpenDevice routine grants access to the narrator device.
    OpenDevice checks the unit number, and if non-zero, returns
    an error (ND_UnitErr).  If this is the first time the driver
    has been opened, OpenDevice will attempt to open the audio
    device and allocate the driver's static buffers.  If either
    of these operations fail, an error is returned (see the .h,i
    files for possible error return codes).  Next, OpenDevice
    (done for all opens, not just the first one) initializes the
    user's @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block (IORB).  Default values for sex, rate,
    pitch, pitch mode, sampling frequency, and mouths are set in
    the appropriate fields of the IORB.  Note that if users wish
    to use non-default values for these parms, the values must
    be set after the open is done.  OpenDevice then assigns a
    pseudo-unit number to the IORB for use in synchronizing read
    and write requests.  See the @{"CMD_READ" Link "CMD_READ"} command for more details.
    Finally, OpenDevice stores the device node pointer in the
    IORB and clears the delayed expunge bit.

INPUTS
    deviceName - must be "narrator.device"
    unitNumber - must be 0
    iORequest  - a pointer to the user's @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block
                 ( need not be initialized )
    flags      - not used

RESULTS
    error - same as io_Error field of IORB

    @{"IORequest" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 17} block fields set:
       rate    - 150 words/minute
       pitch   - 110 Hz
       mode    - Natural
       sex     - Male
       mouths  - Off
       sampfreq - 22200
       volume  - 64 (max)

BUGS

SEE ALSO
    narrator.device/OpenDevice, @{"narrator.device/CMD_READ" Link "CMD_READ"},
    @{"exec/io.h" Link "ADCD_v1.2:Inc&AD1.3/Includes/exec/io.h/Main" 0}

@EndNode

