AmiCradleA new chapter for the Amiga

API docs / Autodocs / acaudio.doc

API · Autodoc

acaudio.audio (AHI driver) autodoc

acaudio.audio, AHI's driver for ACAHI: its modes, and what it does with each of AHI's driver calls

acaudio/--background--

   PURPOSE
        acaudio.audio is AHI's driver for ACAHI, AmiCradle's sound
        board (acahi.doc). Programs never open it: they use ahi.device or
        AHI's library calls as on any Amiga, and AHI calls this driver
        when a unit or a program picks one of its modes. This file says
        what the driver does with each of AHI's driver calls, so that a
        program's author knows what to expect from each mode.

        One m68k binary serves AmigaOS 3.x and AROS 68k. It is a version 6
        driver (it uses PreTimerFunc and PostTimerFunc), so it needs AHI
        6.

   FILES
        DEVS:AHI/acaudio.audio     the driver
        DEVS:AudioModes/ACAUDIO    its modes

   MODES
        0x00AC0001  AmigaChrome: Host mix 16 bit stereo++
                    The board mixes AHI's channels (up to 32) at 44.1 kHz.
                    AHI's channel calls go to the board's voices; the 68k
                    mixes nothing. The mode file sets the driver's own tag
                    AHIDB_UserBase+0 (HostMix) TRUE.

        0x00AC0002  AmigaChrome: HiFi 32 bit stereo++
        0x00AC0003  AmigaChrome: 16 bit stereo++
                    AHI mixes on the 68k with its HiFi or its 16-bit
                    mixer, at 8 to 48 kHz, and the driver streams what
                    it mixes to the board.

        In every mode the board's sound reaches the PC beside Paula's,
        as its own source in Cradle's mixer ("NAME · AHI").

   SHARED (6.1)
        Several AHI_AllocAudio() at once share the board. On Host mix
        each takes its own voices out of the 32 and its own sounds out of
        the 1,024, and fails when not enough are free, with nothing taken.
        Its voices' ends call its own SoundFunc, with its own channel
        numbers. The board has one timer: it ticks at the fastest
        PlayerFunc rate a started client asks for, and each client's
        PlayerFunc runs at its own rate from those ticks. Each client's
        master volume is its own. ahi.device's units are clients like any
        program, so a program on Host mix (OpenAL.module's Voices) plays
        beside them.

        The 68k-mixed modes stay one at a time: the board has one
        stream. The stream can play beside Host mix clients.

        6.0 served one AHI_AllocAudio() at a time.

   NOT YET
        Recording (AHISF_RECORD, AHIDB_Record is FALSE). In Host mix,
        echo and DSP masks return AHIE_UNKNOWN; use another mode for them.

   SEE ALSO
        acahi.doc, docs/howto/08-ahi-sound.md,
        AHI's own autodocs (ahi.doc, ahi_sub.doc)

acaudio/AHIsub_AllocAudio

   NAME
        AHIsub_AllocAudio -- a share of the board for an AHI_AllocAudio()

   SYNOPSIS
        flags = AHIsub_AllocAudio( tags, audioctrl )
        D0                         A1    A2

   FUNCTION
        The first client finds the ACAHI board (AmiCradle Team or 2011,
        product 4), resets it and adds the interrupt server on INTB_PORTS,
        named "acaudio.audio". tags are the mode's tags from
        DEVS:AudioModes/ACAUDIO; the HostMix tag picks how the driver
        works.

        Host mix: takes ahiac_Channels voices and ahiac_Sounds sound slots
        that no other client has, each voice silent, and sets
        ahiac_MixFreq to 44100, the rate the board mixes at.

        The others: takes the board's stream, and keeps ahiac_MixFreq
        between 4000 and 96000.

   RESULT
        Host mix: AHISF_KNOWSTEREO | AHISF_KNOWHIFI. Without
        AHISF_MIXING AHI sends every channel call to the driver; without
        AHISF_TIMING the driver calls PlayerFunc from the board's timer.

        The others: AHISF_MIXING | AHISF_TIMING | AHISF_KNOWSTEREO |
        AHISF_KNOWHIFI.

        AHISF_ERROR when there is no board, fewer voices or sound slots
        are free than asked for, another client has the stream, or memory
        runs out.

acaudio/AHIsub_FreeAudio

   NAME
        AHIsub_FreeAudio -- give the share back

   SYNOPSIS
        AHIsub_FreeAudio( audioctrl )
                          A2

   FUNCTION
        Stops playing, silences the client's voices, unloads its sounds and
        frees the driver's data. The last client removes the interrupt
        server and resets the board.

acaudio/AHIsub_Disable

   NAME
        AHIsub_Disable -- hold back SoundFunc and PlayerFunc
        AHIsub_Enable -- let them run again

   SYNOPSIS
        AHIsub_Disable( audioctrl )
        AHIsub_Enable( audioctrl )
                        A2

   FUNCTION
        Disable clears the board's INTENA; Enable sets it back. They
        nest, across every client: the last Enable is the one that
        counts, so one client's Disable holds every client's hooks for
        as long. Requests raised meanwhile wait in the board's INTREQ and
        are served at the last Enable; at most four PlayerFunc calls catch
        up a long wait.

        Sound goes on playing: the voices and the stream need no 68k.

acaudio/AHIsub_Start

   NAME
        AHIsub_Start -- start playing

   SYNOPSIS
        error = AHIsub_Start( flags, audioctrl )
        D0                    D0     A2

   FUNCTION
        Host mix: the client's voices go on from where they were (before
        the first Start, and after Stop, they are held at frequency 0),
        the board's timer runs at the fastest ahiac_PlayerFreq of the
        clients started (when they have a PlayerFunc), and the voices
        play. Its voices' events call its SoundFunc, and the timer's
        ticks its PlayerFunc at its own rate, from the interrupt server,
        as AHI's own mixer would call them.

        The others: starts the driver's task ("acaudio.audio", priority
        20). For each buffer it calls PlayerFunc, then PreTimerFunc, then
        MixerFunc unless AHI's CPU limit says to skip it (the buffer is
        silence then, and the music keeps its time), then PostTimerFunc,
        and submits the buffer to the board, which copies
        it at once. It keeps three buffers queued, and the board's DONE
        interrupt wakes it to mix the next. The music is timed by the
        board's audio clock, so it plays at the right speed whatever the
        CPU's pace.

   RESULT
        AHIE_OK; AHIE_NOMEM; AHIE_UNKNOWN for AHISF_RECORD (not yet), or
        a mix rate or buffer type the board does not play.

acaudio/AHIsub_Update

   NAME
        AHIsub_Update -- the player's frequency or buffer size changed

   SYNOPSIS
        AHIsub_Update( flags, audioctrl )
                       D0     A2

   FUNCTION
        Host mix: the client's PlayerFunc at the new ahiac_PlayerFreq (the
        board's timer at the fastest of the clients').
        The others: nothing; the task reads ahiac_BuffSamples before
        every mix.

acaudio/AHIsub_Stop

   NAME
        AHIsub_Stop -- stop playing

   SYNOPSIS
        AHIsub_Stop( flags, audioctrl )
                     D0     A2

   FUNCTION
        Host mix: holds the client's voices where they are (frequency 0)
        and calls none of its hooks until the next Start. Sounds stay
        loaded.
        The others: stops the task and waits for it to end. Alone on the
        board, the stream is reset; beside Host mix clients, what it had
        queued plays out, and the next Start numbers its buffers on.

acaudio/AHIsub_SetVol

   NAME
        AHIsub_SetVol -- a channel's volume and panning

   SYNOPSIS
        result = AHIsub_SetVol( channel, volume, pan, audioctrl, flags )
        D0                      D0       D1      D2   A2         D3

   FUNCTION
        Host mix: the channel's voice takes volume and pan, now with
        AHISF_IMM, else when its sound playing ends (acahi.doc,
        ACAHI_V_CMD). A negative volume inverts the sound. The board has
        no surround: a negative pan plays as its absolute value.

   RESULT
        Host mix: AHIE_OK. The others: AHIS_UNKNOWN, so AHI does it.

acaudio/AHIsub_SetFreq

   NAME
        AHIsub_SetFreq -- a channel's playing rate

   SYNOPSIS
        result = AHIsub_SetFreq( channel, freq, audioctrl, flags )
        D0                       D0       D1    A2         D2

   FUNCTION
        Host mix: the channel's voice plays freq frames a second, now
        with AHISF_IMM, else when its sound playing ends. AHI_MIXFREQ is
        44100. The board resamples with linear interpolation. A freq of
        0 pauses the channel, silent, where it is, until another freq.

   RESULT
        Host mix: AHIE_OK. The others: AHIS_UNKNOWN.

acaudio/AHIsub_SetSound

   NAME
        AHIsub_SetSound -- what a channel plays

   SYNOPSIS
        result = AHIsub_SetSound( channel, sound, offset, length,
        D0                        D0       D1     D2      D3
                                  audioctrl, flags )
                                  A2         D4

   FUNCTION
        Host mix: the channel's voice plays sound from frame offset,
        length frames (0: to the end; below 0: backwards), over and
        over. With AHISF_IMM it starts now (and an end of the sound
        before it that SoundFunc has not been told yet is not told);
        without, when the sound playing ends, and that moment calls
        SoundFunc. AHI_NOSOUND silences the channel.

   RESULT
        Host mix: AHIE_OK, or AHIE_UNKNOWN for a sound not loaded or a
        part outside it. The others: AHIS_UNKNOWN.

acaudio/AHIsub_SetEffect

   NAME
        AHIsub_SetEffect -- an effect on the mix

   SYNOPSIS
        result = AHIsub_SetEffect( effect, audioctrl )
        D0                         A0      A2

   FUNCTION
        Host mix: AHIET_MASTERVOLUME sets the client's master gain, which
        the driver scales by 2 / channels when there are more than two
        channels, as AHI's own mixer does, and applies to each of its
        voices' volumes (now, and the one set for when the sound ends),
        the board's MASTER staying at unity. Cancelling it goes back to
        full.

        AHIET_CHANNELINFO: after each PlayerFunc the driver fills
        ahieci_Offset[] with the frame each channel's sound is playing
        (the board's V_POS) and calls ahieci_Func, as AHI's mixer does
        after each pass. ahi.device asks for it on every unit it opens,
        and a unit does not open without it.

   RESULT
        Host mix: AHIE_OK for the master volume and channel info,
        AHIE_UNKNOWN for echo and DSP masks. The others: AHIS_UNKNOWN, so
        AHI's mixer does them all.

acaudio/AHIsub_LoadSound

   NAME
        AHIsub_LoadSound -- tell the board where a sound is
        AHIsub_UnloadSound -- forget it

   SYNOPSIS
        result = AHIsub_LoadSound( sound, type, info, audioctrl )
        D0                         D0     D1    A0    A2

        result = AHIsub_UnloadSound( sound, audioctrl )
        D0                           D0     A2

   FUNCTION
        Host mix: loads AHI's struct AHISampleInfo into the board's slot
        for the client's sound (0 to ahiac_Sounds - 1). The board reads the frames from Amiga RAM as
        they play, so AHIST_SAMPLE and AHIST_DYNAMICSAMPLE sounds are the
        same to it: a program can keep writing a dynamic sound while it
        plays. Unloading silences the channels playing it.

        Sample types: AHIST_M8S, AHIST_S8S, AHIST_M16S, AHIST_S16S,
        AHIST_M32S and AHIST_S32S.

        An ahisi_Address of 0 with an ahisi_Length of 0xFFFFFFFF is AHI's
        "all of memory" sound: AHIsub_SetSound's offset is then where
        the frames are, checked as each segment starts.

   RESULT
        Host mix: AHIE_OK; AHIE_BADSOUNDTYPE for anything but a sample
        (AHIST_INPUT); AHIE_BADSAMPLETYPE for another sample type;
        AHIE_NOMEM for a sound number past the client's ahiac_Sounds;
        AHIE_UNKNOWN for a sound not all in RAM. The others: AHIS_UNKNOWN.

acaudio/AHIsub_GetAttr

   NAME
        AHIsub_GetAttr -- what the mode offers

   SYNOPSIS
        value = AHIsub_GetAttr( attribute, argument, default, tags,
        D0                      D0         D1        D2       A1
                                audioctrl )
                                A2

   FUNCTION
        AHIDB_Bits             16
        AHIDB_MaxChannels      Host mix: 32
        AHIDB_Frequencies      Host mix: 1 (44100); the others: 7
                               (8000, 11025, 16000, 22050, 32000,
                               44100, 48000)
        AHIDB_Frequency        the argument'th of those
        AHIDB_Index            the nearest to argument
        AHIDB_MaxPlaySamples   the others: 65536
        AHIDB_Record           FALSE
        AHIDB_FullDuplex       FALSE
        AHIDB_Realtime         TRUE
        AHIDB_Inputs           0
        AHIDB_Outputs          1, named "Cradle"
        AHIDB_Author, AHIDB_Copyright, AHIDB_Version, AHIDB_Annotation

        Anything else returns default.

acaudio/AHIsub_HardwareControl

   NAME
        AHIsub_HardwareControl -- levels and inputs

   SYNOPSIS
        result = AHIsub_HardwareControl( attribute, argument,
        D0                               D0         D1
                                         audioctrl )
                                         A2

   FUNCTION
        Returns 0 for everything: the board has no inputs, and its level
        is set on the PC, in Cradle's mixer.