home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 1 / Mecomp-CD.iso / amiga / player / ahi / developer / docs / ahi.doc < prev    next >
Encoding:
Text File  |  1996-07-12  |  45.6 KB  |  1,415 lines
  1. TABLE OF CONTENTS
  2. 0001 ahi.device/--background--
  3. 0002 ahi.device/AHI_AllocAudioA
  4. 0003 ahi.device/AHI_AllocAudioRequestA
  5. 0004 ahi.device/AHI_AudioRequestA
  6. 0005 ahi.device/AHI_BestAudioIDA
  7. 0006 ahi.device/AHI_ControlAudioA
  8. 0007 ahi.device/AHI_FreeAudio
  9. 0008 ahi.device/AHI_FreeAudioRequest
  10. 0009 ahi.device/AHI_GetAudioAttrsA
  11. 0010 ahi.device/AHI_KillAudio
  12. 0011 ahi.device/AHI_LoadSound
  13. 0012 ahi.device/AHI_NextAudioID
  14. 0013 ahi.device/AHI_SetEffect
  15. 0014 ahi.device/AHI_SetFreq
  16. 0015 ahi.device/AHI_SetSound
  17. 0016 ahi.device/AHI_SetVol
  18. 0017 ahi.device/AHI_UnloadSound
  19.  
  20. ahi.device/--background--
  21.  
  22. PURPOSE
  23.  
  24.        The 'ahi.device' was first created because the lack of standards
  25.        when it comes to sound cards on the Amiga. Another reason was to
  26.        make it easier to write multi-channel music programs.
  27.  
  28.        This device is by no means the final and perfect solution. But
  29.        hopefully, it can evolve into something useful until AT brings you
  30.        The Real Thing (TM).
  31.  
  32.  
  33. OVERVIEW
  34.  
  35.        * Driver based
  36.  
  37.        Each supported sound card is controlled by a library-based audio
  38.        driver. For a 'dumb' sound card, a new driver should be written in
  39.        a few hours. For a 'smart' sound card, it is possible to utilize an
  40.        on-board DSP, for example, to maximize performance and sound
  41.        quality. For sound cards with own DSP but little or no memory, it is
  42.        possible to use the main CPU to mix channels and do the post-
  43.        processing with the DSP.
  44.  
  45.        * Fast, powerful mixing routines (yeah, right... haha)
  46.  
  47.        The device's mixing routines mix 8- or 16-bit signed samples
  48.        located in Fast-RAM and outputs 16-bit mono or stereo (with stereo
  49.        panning if desired) data, using any number of channels (as long as
  50.        'any' means less than 128...). Tables can be used speed the mixing
  51.        up (especially when using 8-bit samples). The samples can have any
  52.        length (including odd) and can have any number of loops.
  53.  
  54.        * Support for non-realtime mixing
  55.  
  56.        By providing a timing feature, it is possible to create high-
  57.        quality output even if the processing power is lacking, by saving
  58.        the output to disk, for example as an IFF AIFF or 8SXV file.
  59.  
  60.        * Audio database
  61.  
  62.        Uses ID codes, much like Screenmode IDs, to select the many
  63.        parameters that can be set. The functions to access the audio
  64.        database are not too different from those in 'graphics.library'.
  65.        Audio modes are added to the database with the tool 'AddAudioModes',
  66.        which either takes IFF-AHIM file(s) as argument or scans
  67.        'DEVS:AudioModes/' and adds all files found there. The device also
  68.        features a requester to get an ID code from the user.
  69.  
  70.        * Future Compatible
  71.  
  72.        When AmigaOS gets device-independent audio worth it's name, it should
  73.        not be too difficult to write a driver for AHI, allowing applications
  74.        using 'ahi.device' to automatically use the new OS interface. At
  75.        least I hope it wont.
  76.  
  77.  
  78. PROGRAMMING GUIDELINES
  79.  
  80.         * Follow the rules
  81.  
  82.         It's really simple. If I tell you to check return values, check
  83.         sample types when recording, don't trash d2-d7/a2-a6 in Hooks, or
  84.         don't call AHI_ControlAudio() with the AHIC_Play tag from interrups
  85.         or Hooks, you do as you are told.
  86.  
  87.         * The library base
  88.  
  89.         The AHIBase structure is private, so are the sub libraries' library
  90.         base structures. Don't try to be clever.
  91.  
  92.         * The Audio Database
  93.  
  94.         The implementation of the database is private, and may change any
  95.         time. 'ahi.device' provides functions access the information in
  96.         the database (AHI_NextAudioID(), AHI_GetAudioAttrsA() and
  97.         AHI_BestAudioIDA()).
  98.  
  99.         * User Hooks
  100.  
  101.         All user Hooks must follow normal register conventions, which means
  102.         that d2-d7 and a2-a6 must be presered. They may be called from an
  103.         interrupt, but you cannot count on that, it can be your own process
  104.         or another process. Don't assume system is in single-thread mode.
  105.         Never spend much time in a Hook, get the work done as quick as
  106.         possible and then return.
  107.  
  108.         * Function calls from other tasks, interrupts or user Hooks
  109.  
  110.         The AHIAudioCtrl structure may not be shared with other tasks/
  111.         threads. The task that called AHI_AllocAudioA() must do all other
  112.         calls too (except those callable from interrupts).
  113.  
  114.         Only calls specifically said to be callable from interrups may be
  115.         called from user Hooks or interrupts. Note that AHI_ControlAudioA()
  116.         have some tags that must not be present when called from an
  117.         interrupt.
  118.  
  119.         * AHI_SetVol(), AHI_SetFreq() and AHI_SetSound() Flags
  120.  
  121.         These function calls take some flags as arguments. Currently, only
  122.         one flag is defined, AHISB_IMM, which causes the changes to take
  123.         effecy immediately. THIS FLAG SHOULD *NEVER* BE SET when you call
  124.         these routines _from_ a SoundFunc. Likewise, THIS FLAG SHOULD
  125.         *ALWAYS* BE SET, when calling these routines _outside_ a SoundFunc,
  126.         for example from the PlayerFunc. This is very important.
  127.  
  128.         * System requirements
  129.  
  130.         V37 of the system libraries are required.
  131.  
  132.         'ahi.device', or rather most audio drivers, need multitasking to be
  133.         turned on to function properly. Don't turn it off when using the
  134.         device.
  135.  
  136.         Some drivers use 'realtime.library', which must be present for those
  137.         drivers to work. 'realtime.library' needs a free CIA timer. If your
  138.         application uses a CIA timer, it is strongly recommended that you
  139.         use the PlayerFunc in 'ahi.device' instead.
  140.  
  141.  
  142.  
  143.  
  144. ahi.device/AHI_AllocAudioA
  145.  
  146. NAME
  147.        AHI_AllocAudioA -- allocates and initializes the audio hardware
  148.        AHI_AllocAudio -- varargs stub for AHI_AllocAudioA()
  149.  
  150.  
  151. SYNOPSIS
  152.        audioctrl = AHI_AllocAudioA( tags );
  153.        D0                           A1
  154.  
  155.        struct AHIAudioCtrl *AHI_AllocAudioA( struct TagItem * );
  156.  
  157.        audioctrl = AHI_AllocAudio( tag1, ... );
  158.  
  159.        struct AHIAudioCtrl *AHI_AllocAudio( Tag, ... );
  160.  
  161.  
  162. FUNCTION
  163.        Allocates and initializes the audio hardware, selects the best
  164.        mixing routine (if neccessary) according to the supplied tags.
  165.        To start playing you first need to call AHI_ControlAudioA().
  166.  
  167.  
  168. INPUTS
  169.        tags - A pointer to a tag list.
  170.  
  171.  
  172. TAGS
  173.  
  174.        AHIA_AudioID (ULONG) - The audio mode to use.
  175.  
  176.        AHIA_MixFreq (ULONG) - Desired mixing frequency. The actual
  177.            mixing rate may or may not be exactly what you asked for.
  178.  
  179.        AHIA_Channels (UWORD) - Number of channel to use. The actual
  180.            number of channels used will be equal or grater than the
  181.            requested. If too many channels were requested, this function
  182.            will fail. This tag must be supplied.
  183.  
  184.        AHIA_Sounds (UWORD) - Number of sounds to use. This tag must be
  185.            supplied.
  186.  
  187.        AHIA_SoundFunc (struct Hook *) - A function to call each time
  188.            when a sound has been started. The function receives the
  189.            following parameters:
  190.                A0 - (struct Hook *)
  191.                A2 - (struct AHIAudioCtrl *)
  192.                A1 - (struct AHISoundMessage *)
  193.            The hook may be called from an interrupt, so normal interrupt
  194.            restrictions apply.
  195.            The called function should follow normal register conventions,
  196.            which means that d2-d7 and a2-a6 must be preserved.
  197.  
  198.        AHIA_PlayerFunc (struct Hook *) - A function to be called at regular
  199.            intervals. By using this hook there is no need for music players
  200.            to use other timing, such as VBLANK or CIA timers. But the real
  201.            reason it's present is that it makes it possible to do non-
  202.            realtime mixing to disk.
  203.            Using this interrupt source is currently the only supported way
  204.            to ensure that no mixing occurs between calls to AHI_SetVol(),
  205.            AHI_SetFreq() or AHI_SetSound().
  206.            If the sound playback is done without mixing, 'realtime.library'
  207.            is used to provide timing. The function receives the following
  208.            parameters:
  209.                A0 - (struct Hook *)
  210.                A2 - (struct AHIAudioCtrl *)
  211.                A1 - Undefined.
  212.            Do not assume A1 contains any particular value!
  213.            The hook may be called from an interrupt, so normal interrupt
  214.            restrictions apply.
  215.            The called function should follow normal register conventions,
  216.            which means that d2-d7 and a2-a6 must be preserved.
  217.  
  218.        AHIA_PlayerFreq (Fixed) - If non-zero, enables timing and specifies
  219.            how many times per second PlayerFunc will be called. This must
  220.            be specified if AHIA_PlayerFunc is! Do not use any extreme
  221.            frequences. The result of MixFreq/PlayerFreq must fit an UWORD,
  222.            ie it must be less or equal to 65535. It is also suggested that
  223.            you keep the result over 80. For normal use this should not be a
  224.            problem.
  225.  
  226.        AHIA_MinsPlayerFreq (Fixed) - The minimum frequency (AHIA_PlayerFreq)
  227.            you will use. You should always supply this if you are using the
  228.            device's interrupt feature!
  229.  
  230.        AHIA_MaxPlayerFreq (Fixed) - The maximum frequency (AHIA_PlayerFreq)
  231.            you will use. You should always supply this if you are using the
  232.            device's interrupt feature!
  233.  
  234.        AHIA_RecordFunc (struct Hook *) - This function will be called
  235.            regulary when sampling is turned on (see AHI_ControlAudioA())
  236.            with the following parameters:
  237.                A0 - (struct Hook *)
  238.                A2 - (struct AHIAudioCtrl *)
  239.                A1 - (struct AHIRecordMessage *)
  240.            The message (AHIRecordMessage) is filled as follows:
  241.                ahirm_Buffer - Pointer to the samples. The buffer is valid
  242.                    until next time the Hook is called.
  243.                ahiim_Length - Number of sample FRAMES in buffer.
  244.                    To get the size in bytes, multiply by 4 if ahiim_Type is
  245.                    AHIST_S16S.
  246.                ahiim_Type - Always AHIST_S16S at the moment, but you *must*
  247.                    check this, since it may change in the future!
  248.            The hook may be called from an interrupt, so normal interrupt
  249.            restrictions apply. Signal a process if you wish to save the
  250.            buffer to disk. The called function should follow normal register
  251.            conventions, which means that d2-d7 and a2-a6 must be preserved.
  252.        *** NOTE: The function MUST return NULL (in d0). This was previously
  253.            not documented. Now you know.
  254.  
  255.        AHIA_UserData (APTR) - Can be used to initialise the ahiac_UserData
  256.            field.
  257.  
  258.  
  259. RESULT
  260.        A pointer to an AHIAudioCtrl structure or NULL if an error occured.
  261.  
  262.  
  263. EXAMPLE
  264.  
  265.  
  266. NOTES
  267.        The AHIA_RecordFunc function must return NULL!
  268.  
  269.        AHIA_PlayerFreq, AHIA_MinsPlayerFreq and AHIA_MaxPlayerFreq used to
  270.        be ULONGs. Now they have been redefined as Fixed. In order not to
  271.        break old programs, all values below 65536 (i.e. below 1.0 Hz) will
  272.        be treated as ULONGs. This klude will be removed later.
  273.  
  274. BUGS
  275.  
  276.  
  277. SEE ALSO
  278.        AHI_FreeAudio(), AHI_ControlAudioA()
  279.  
  280.  
  281.  
  282.  
  283. ahi.device/AHI_AllocAudioRequestA
  284.  
  285. NAME
  286.        AHI_AllocAudioRequestA -- allocate an audio mode requester.
  287.        AHI_AllocAudioRequest -- varargs stub for AHI_AllocAudioRequestA()
  288.  
  289.  
  290. SYNOPSIS
  291.        requester = AHI_AllocAudioRequestA( tags );
  292.        D0                                  A0
  293.  
  294.        struct AHIAudioModeRequester *AHI_AllocAudioRequestA(
  295.            struct TagItem * );
  296.  
  297.        requester = AHI_AllocAudioRequest( tag1, ... );
  298.  
  299.        struct AHIAudioModeRequester *AHI_AllocAudioRequest( Tag, ... );
  300.  
  301.  
  302. FUNCTION
  303.        Allocates an audio mode requester data structure.
  304.  
  305.  
  306. INPUTS
  307.        tags - A pointer to an optional tag list specifying how to initialize
  308.            the data structure returned by this function. See the
  309.            documentation for AHI_AudioRequestA() for an explanation of how
  310.            to use the currently defined tags.
  311.  
  312.  
  313. RESULT
  314.        requester - An initialized requester data structure, or NULL on
  315.            failure. 
  316.  
  317.  
  318. EXAMPLE
  319.  
  320.  
  321. NOTES
  322.        The requester data structure is READ-ONLY and can only be modified
  323.        by using tags!
  324.  
  325.  
  326. BUGS
  327.  
  328.  
  329. SEE ALSO
  330.       AHI_AudioRequestA(), AHI_FreeAudioRequest()
  331.  
  332.  
  333.  
  334.  
  335. ahi.device/AHI_AudioRequestA
  336.  
  337. NAME
  338.        AHI_AudioRequestA -- get an audio mode from user using an requester.
  339.        AHI_AudioRequest -- varargs stub for AHI_AudioRequestA()
  340.  
  341.  
  342. SYNOPSIS
  343.        result = AHI_AudioRequestA( requester, tags );
  344.        D0                          A0         A1
  345.  
  346.        BOOL AHI_AudioRequestA( struct AHIAudioModeRequester *,
  347.            struct TagItem * );
  348.  
  349.        result = AHI_AudioRequest( requester, tag1, ... );
  350.  
  351.        BOOL AHI_AudioRequest( struct AHIAudioModeRequester *, Tag, ... );
  352.  
  353.  
  354. FUNCTION
  355.        Prompts the user for an audio mode, based on the modifying tags.
  356.        If the user cancels or the system aborts the request, FALSE is
  357.        returned, otherwise the requester's data structure relects the
  358.        user input.
  359.  
  360.        Note that tag values stay in effect for each use of the requester
  361.        until they are cleared or modified by passing the same tag with a
  362.        new value.
  363.  
  364.  
  365. TAGS
  366.        Tags used for the requester (they look remarkable similar to the
  367.        screen mode requester in asl, don't they? ;-) )
  368.  
  369.        AHIR_Window (struct Window *) - Parent window of requester. If no
  370.            AHIR_Screen tag is specified, the window structure is used to
  371.            determine on which screen to open the requesting window.
  372.  
  373.        AHIR_PubScreenName (STRPTR) - Name of a public screen to open on.
  374.            This overrides the screen used by AHIR_Window.
  375.  
  376.        AHIR_Screen (struct Screen *) - Screen on which to open the
  377.            requester. This overrides the screen used by AHIR_Window or by
  378.            AHIR_PubScreenName.
  379.  
  380.        AHIR_PrivateIDCMP (BOOL) - When set to TRUE, this tells AHI to
  381.            allocate a new IDCMP port for the requesting window. If not
  382.            specified or set to FALSE, and if AHIR_Window is provided, the
  383.            requesting window will share AHIR_Window's IDCMP port.
  384.  
  385.        AHIR_IntuiMsgFunc (struct Hook *) - A function to call whenever an
  386.            unknown Intuition message arrives at the message port being used
  387.            by the requesting window. The function receives the following
  388.            parameters:
  389.                A0 - (struct Hook *)
  390.                A1 - (struct IntuiMessage *)
  391.                A2 - (struct AHIAudioModeRequester *)
  392.  
  393.        AHIR_SleepWindow (BOOL) - When set to TRUE, this tag will cause the
  394.            window specified by AHIR_Window to be "put to sleep". That is, a
  395.            busy pointer will be displayed in the parent window, and no
  396.            gadget or menu activity will be allowed. This is done by opening
  397.            an invisible Intuition Requester in the parent window.
  398.  
  399.        AHIR_UserData (APTR) - A 32-bit value that is simply copied in the
  400.            ahiam_UserData field of the requester structure.
  401.  
  402.        AHIR_TextAttr (struct TextAttr *) - Font to be used for the
  403.            requesting window's gadgets and menus. If this tag is not
  404.            provided or its value is NULL, the default font of the screen
  405.            on which the requesting window opens will be used. This font
  406.            must already be in memory as AHI calls OpenFont() and not
  407.            OpenDiskFont().
  408.  
  409.        AHIR_Locale (struct Locale *) - Locale to use for the requesting
  410.            window. This determines the language used for the requester's
  411.            gadgets and menus. If this tag is not provided or its value is
  412.            NULL, the system's current default locale will be used.
  413.            This tag does not work yet.
  414.  
  415.        AHIR_TitleText (STRPTR) - Title to use for the requesting window.
  416.            Default is no title.
  417.  
  418.        AHIR_PositiveText (STRPTR) - Label of the positive gadget in the
  419.            requester. English default is "OK".
  420.  
  421.        AHIR_NegativeText (STRPTR) - Label of the negative gadget in the
  422.            requester. English default is "Cancel".
  423.  
  424.        AHIR_InitialLeftEdge (WORD) - Suggested left edge of requesting
  425.            window.
  426.  
  427.        AHIR_InitialTopEdge (WORD) - Suggested top edge of requesting
  428.            window.
  429.  
  430.        AHIR_InitialWidth (WORD) - Suggested width of requesting window.
  431.  
  432.        AHIR_InitialHeight (WORD) - Suggested height of requesting window.
  433.  
  434.        AHIR_InitialAudioID (ULONG) - Initial setting of the Mode list view
  435.            gadget (ahiam_AudioID). Default is ~0 (AHI_INVALID_ID), which
  436.            means that no mode will be selected.
  437.  
  438.        AHIR_InitialMixFreq (ULONG) - Initial setting of the frequency
  439.            slider. Default is the lowest frequency supported.
  440.  
  441.        AHIR_InitialInfoOpened (BOOL) - Whether to open the property
  442.            information window automatically. Default is FALSE.
  443.            This tag does not work yet.
  444.  
  445.        AHIR_InitialInfoLeftEdge (WORD) - Initial left edge of information
  446.            window.
  447.            This tag does not work yet.
  448.  
  449.        AHIR_InitialInfoTopEdge (WORD) - Initial top edge of information
  450.            window.
  451.            This tag does not work yet.
  452.  
  453.        AHIR_DoMixFreq (BOOL) - Set this tag to TRUE to cause the requester
  454.            to display the frequency slider gadget. Default is FALSE.
  455.  
  456.        AHIR_FilterFunc (struct Hook *) - A function to call for each mode
  457.            encountered. If the function returns TRUE, the mode is included
  458.            in the file list, otherwise it is rejected and not displayed. The
  459.            function receives the following parameters:
  460.                A0 - (struct Hook *)
  461.                A1 - (ULONG) mode id
  462.                A2 - (struct AHIAudioModeRequester *)
  463.  
  464.        AHIR_FilterTags (struct TagItem *) - A pointer to a tag list used to
  465.            filter modes away, like AHIR_FilterFunc does. The tags are the
  466.            same as AHI_BestAudioIDA() takes as arguments. See that function
  467.            for an explanation of each tag.
  468.  
  469.  
  470. INPUTS
  471.        requester - Requester structure allocated with
  472.            AHI_AllocAudioRequestA(). If this parameter is NULL, this
  473.            function will always return FALSE with a dos.library/IoErr()
  474.            result of ERROR_NO_FREE_STORE.
  475.        tags - Pointer to an optional tag list which may be used to control
  476.            features of the requester.
  477.  
  478.  
  479. RESULT
  480.        result - FALSE if the user cancelled the requester or if something
  481.            prevented the requester from opening. If TRUE, values in the
  482.            requester structure will be set.
  483.  
  484.            If the return value is FALSE, you can look at the result from the
  485.            dos.library/IoErr() function to determine whether the requester
  486.            was cancelled or simply failed to open. If dos.library/IoErr()
  487.            returns 0, then the requester was cancelled, any other value
  488.            indicates a failure to open. Current possible failure codes are
  489.            ERROR_NO_FREE_STORE which indicates there was not enough memory,
  490.            and ERROR_NO_MORE_ENTRIES which indicates no modes were available
  491.            (usually because the application filter hook filtered them all
  492.            away).
  493.  
  494.  
  495. EXAMPLE
  496.  
  497.  
  498. NOTES
  499.        The requester data structure is READ-ONLY and can only be modified
  500.        by using tags!
  501.  
  502.  
  503. BUGS
  504.        AHIR_Locale and the information window is not inplemented.
  505.  
  506.  
  507. SEE ALSO
  508.       AHI_AllocAudioRequestA(), AHI_FreeAudioRequest()
  509.  
  510.  
  511.  
  512.  
  513. ahi.device/AHI_BestAudioIDA
  514.  
  515. NAME
  516.        AHI_BestAudioIDA -- calculate the best ModeID with given parameters
  517.        AHI_BestAudioID -- varargs stub for AHI_BestAudioIDA()
  518.  
  519.  
  520. SYNOPSIS
  521.        ID = AHI_BestAudioIDA( tags );
  522.        D0                     A1
  523.  
  524.        ULONG AHI_BestAudioIDA( struct TagItem * );
  525.  
  526.        ID = AHI_BestAudioID( tag1, ... );
  527.  
  528.        ULONG AHI_BestAudioID( Tag, ... );
  529.  
  530.  
  531. FUNCTION
  532.        Determines the best AudioID to fit the parameters set in the tag
  533.        list.
  534.  
  535.  
  536. INPUTS
  537.        tags - A pointer to a tag list. Only the tags present matter.
  538.  
  539.  
  540. TAGS
  541.        Many combinations are probably stupid to ask for, like not supporting
  542.        panning or recording.
  543.  
  544.        AHIDB_AudioID (ULONG) - The mode must use the same audio hardware
  545.            as this mode does.
  546.  
  547.        AHIDB_Volume (BOOL) - If TRUE: mode must support volume changes.
  548.            If FALSE: mode must not support volume changes.
  549.  
  550.        AHIDB_Stereo (BOOL) - If TRUE: mode must have stereo output.
  551.            If FALSE: mode must not have stereo output (=mono).
  552.  
  553.        AHIDB_Panning (BOOL) - If TRUE: mode must support volume panning.
  554.            If FALSE: mode must not support volume panning. 
  555.  
  556.        AHIDB_HiFi (BOOL) - If TRUE: mode must have HiFi output.
  557.            If FALSE: mode must not have HiFi output.
  558.  
  559.        AHIDB_PingPong (BOOL) - If TRUE: mode must support playing samples
  560.            backwards. If FALSE: mode must not support playing samples
  561.            backwards.
  562.  
  563.        AHIDB_Record (BOOL) - If TRUE: mode must support recording. If FALSE:
  564.            mode must not support recording.
  565.  
  566.        AHIDB_Realtime (BOOL) - If TRUE: mode must be realtime. If FALSE:
  567.            take a wild guess.
  568.  
  569.        AHIDB_FullDuplex (BOOL) - If TRUE: mode must be able to record and
  570.            play at the same time.
  571.  
  572.        AHIDB_Bits (UBYTE) - Mode must have greater or equal number of bits.
  573.  
  574.        AHIDB_MaxChannels (UWORD) - Mode must have greater or equal number
  575.            of channels.
  576.  
  577.        AHIDB_MinMixFreq (ULONG) - Lowest mixing frequency supported must be
  578.            less or equal.
  579.  
  580.        AHIDB_MaxMixFreq (ULONG) - Highest mixing frequency must be greater
  581.            or equal.
  582.  
  583.  
  584. RESULT
  585.        ID - The best AudioID to use or AHI_INVALID_ID if none of the modes
  586.            in the audio database could meet the requirements.
  587.  
  588.  
  589. EXAMPLE
  590.  
  591.  
  592. NOTES
  593.  
  594.  
  595. BUGS
  596.  
  597.  
  598. SEE ALSO
  599.       AHI_NextAudioID(), AHI_GetAudioAttrsA()
  600.  
  601.  
  602.  
  603.  
  604. ahi.device/AHI_ControlAudioA
  605.  
  606. NAME
  607.        AHI_ControlAudioA -- change audio attributes
  608.        AHI_ControlAudio -- varargs stub for AHI_ControlAudioA()
  609.  
  610.  
  611. SYNOPSIS
  612.        error = AHI_ControlAudioA( audioctrl, tags );
  613.        D0                         A2         A1
  614.  
  615.        ULONG AHI_ControlAudioA( struct AHIAudioCtrl *, struct TagItem * );
  616.  
  617.        error = AHI_ControlAudio( AudioCtrl, tag1, ...);
  618.  
  619.        ULONG AHI_ControlAudio( struct AHIAudioCtrl *, Tag, ... );
  620.  
  621.  
  622. FUNCTION
  623.        This function should be used to change attributes for a given
  624.        AHIAudioCtrl structure. It is also used to start and stop playback,
  625.        and to control special hardware found on some sound cards.
  626.  
  627.  
  628. INPUTS
  629.        audioctrl - A pointer to an AHIAudioCtrl structure.
  630.        tags - A pointer to a tag list.
  631.  
  632.  
  633. TAGS
  634.        AHIC_Play (BOOL) - Starts (TRUE) and stops (FALSE) playback and
  635.            PlayerFunc.
  636.  
  637.        AHIC_Record (BOOL) - Starts (TRUE) and stops (FALSE) sampling and
  638.            RecordFunc. NOTE: If the audio hardware cannot record at the same
  639.            time as playing samples, the PLAYBACK WILL BE STOPPED.
  640.  
  641.        AHIC_MonitorVolume (Fixed) - Sets the input monitor volume, i.e. how
  642.            much of the input signal is mixed with the output signal while
  643.            recording. Use AHI_GetAudioAttrsA() to find the available range.
  644.            The default is muted, i.e. 0.0.
  645.  
  646.        AHIC_MonitorVolume_Query (Fixed *) - Get the current input monitor
  647.            volume. ti_Data is a pointer to a Fixed variable, where the result
  648.            will be stored.
  649.  
  650.        AHIC_MixFreq_Query (ULONG *) - Get the current mixing frequency.
  651.            ti_Data is a pointer to an ULONG variable, where the result will
  652.            be stored.
  653.  
  654.        AHIC_InputGain (Fixed) - Set the input gain. Use AHI_GetAudioAttrsA()
  655.            to find the available range. Default is no gain, i.e. 1.0. (V2)
  656.  
  657.        AHIC_InputGain_Query (Fixed *) - Get current input gain. (V2)
  658.  
  659.        AHIC_OutputVolume (Fixed) - Set the output volume. Use
  660.            AHI_GetAudioAttrsA() to find the available range. Default is full
  661.            volume, i.e. 1.0. (V2)
  662.  
  663.        AHIC_OutputVolume_Query (Fixed *) - Get current output volume. (V2)
  664.  
  665.        AHIC_Input (ULONG) - Select input source. See AHI_GetAudioAttrsA().
  666.            (V2)
  667.  
  668.        AHIC_Input_Query (ULONG *) - Get current input source. (V2)
  669.  
  670.        AHIC_Output (ULONG) - Select destination for output. See
  671.            AHI_GetAudioAttrsA(). (V2)
  672.  
  673.        AHIC_Output_Query (ULONG *) - Get destination for output. (V2)
  674.  
  675.        The following tags are also recognized by AHI_ControlAudioA(). See
  676.        AHI_AllocAudioA() for what they do. They may be used from interrupts.
  677.  
  678.        AHIA_SoundFunc (struct Hook *)
  679.        AHIA_PlayerFunc (struct Hook *)
  680.        AHIA_PlayerFreq (ULONG)
  681.        AHIA_RecordFunc (struct Hook *)
  682.        AHIA_UserData (APTR)
  683.  
  684.        Note that AHIA_PlayerFreq must never be outside the limits specified
  685.        with AHIA_MinPlayerFreq and AHIA_MaxPlayerFreq!
  686.  
  687.  
  688. RESULT
  689.        An error code, defined in <devices/ahi.h>.
  690.  
  691.  
  692. EXAMPLE
  693.  
  694.  
  695. NOTES
  696.        The AHIC_Play and AHIC_Record tags *must not* be used from
  697.        interrupts.
  698.  
  699.  
  700. BUGS
  701.  
  702.  
  703. SEE ALSO
  704.        AHI_AllocAudioA(), AHI_GetAudioAttrsA(), <devices/ahi.h>
  705.  
  706.  
  707.  
  708.  
  709.  
  710. ahi.device/AHI_FreeAudio
  711.  
  712. NAME
  713.        AHI_FreeAudio -- deallocates the audio hardware
  714.  
  715.  
  716. SYNOPSIS
  717.        AHI_FreeAudio( audioctrl );
  718.                       A2
  719.  
  720.        void AHI_FreeAudio( struct AHIAudioCtrl * );
  721.  
  722.  
  723. FUNCTION
  724.        Deallocates the AHIAudioCtrl structure and any other resources
  725.        allocated by AHI_AllocAudioA(). After this call it must not be used
  726.        by any other functions anymore. AHI_UnloadSound() is automatically
  727.        called for every sound.
  728.  
  729.  
  730. INPUTS
  731.        audioctrl - A pointer to an AHIAudioCtrl structure obtained from
  732.            AHI_AllocAudioA(). If NULL, this function does nothing.
  733.  
  734.  
  735. EXAMPLE
  736.  
  737.  
  738. NOTES
  739.  
  740.  
  741. BUGS
  742.  
  743.  
  744. SEE ALSO
  745.        AHI_AllocAudioA(), AHI_KillAudio(), AHI_UnloadSound()
  746.  
  747.  
  748.  
  749.  
  750.  
  751. ahi.device/AHI_FreeAudioRequest
  752.  
  753. NAME
  754.        AHI_FreeAudioRequest -- frees requester resources 
  755.  
  756.  
  757. SYNOPSIS
  758.        AHI_FreeAudioRequest( requester );
  759.                              A0
  760.  
  761.        void AHI_FreeAudioRequest( struct AHIAudioModeRequester * );
  762.  
  763.  
  764. FUNCTION
  765.        Frees any resources allocated by AHI_AllocAudioRequestA(). Once a
  766.        requester has been freed, it can no longer be used with other calls to
  767.        AHI_AudioRequestA().
  768.  
  769.  
  770. INPUTS
  771.        requester - Requester obtained from AHI_AllocAudioRequestA(), or NULL
  772.        in which case this function does nothing.
  773.  
  774.  
  775. RESULT
  776.  
  777.  
  778. EXAMPLE
  779.  
  780.  
  781. NOTES
  782.  
  783.  
  784. BUGS
  785.  
  786.  
  787. SEE ALSO
  788.       AHI_AllocAudioRequestA()
  789.  
  790.  
  791.  
  792.  
  793. ahi.device/AHI_GetAudioAttrsA
  794.  
  795. NAME
  796.        AHI_GetAudioAttrsA -- examine an audio mode via a tag list
  797.        AHI_GetAudioAttrs -- varargs stub for AHI_GetAudioAttrsA()
  798.  
  799.  
  800. SYNOPSIS
  801.        success = AHI_GetAudioAttrsA( ID, [audioctrl], tags );
  802.        D0                            D0  A2           A1
  803.  
  804.        BOOL AHI_GetAudioAttrsA( ULONG, struct AHIAudioCtrl *,
  805.                                 struct TagItem * );
  806.  
  807.        success = AHI_GetAudioAttrs( ID, [audioctrl], attr1, &result1, ...);
  808.  
  809.        BOOL AHI_GetAudioAttrs( ULONG, struct AHIAudioCtrl *, Tag, ... );
  810.  
  811.  
  812. FUNCTION
  813.        Retrieve information about an audio mode specified by ID or audioctrl
  814.        according to the tags in the tag list. For each entry in the tag
  815.        list, ti_Tag identifies the attribute, and ti_Data is mostly a
  816.        pointer to a LONG (4 bytes) variable where you wish the result to be
  817.        stored.
  818.  
  819.  
  820. INPUTS
  821.        ID - An audio mode identifier or AHI_INVALID_ID.
  822.        audioctrl - A pointer to an AHIAudioCtrl structure, only used if
  823.            ID equals AHI_INVALID_ID. Set to NULL if not used. If set to
  824.            NULL when used, this function returns immediately.
  825.        tags - A pointer to a tag list.
  826.  
  827.  
  828. TAGS
  829.        AHIDB_Volume (ULONG *) - TRUE if this mode supports volume changes.
  830.  
  831.        AHIDB_Stereo (ULONG *) - TRUE if output is in stereo. Unless
  832.            AHIDB_Panning (see below) is TRUE, all even channels are played
  833.            to the left and all odd to the right.
  834.  
  835.        AHIDB_Panning (ULONG *) - TRUE if this mode supports stereo panning.
  836.  
  837.        AHIDB_HiFi (ULONG *) - TRUE if no shortcuts, like predivision, is
  838.            used by the mixing routines.
  839.  
  840.        AHIDB_PingPong (ULONG *) - TRUE if this mode can play samples backwards.
  841.  
  842.        AHIDB_Record (ULONG *) - TRUE if this mode can record samples.
  843.  
  844.        AHIDB_FullDuplex (ULONG *) - TRUE if this mode can record and play at
  845.            the same time.
  846.  
  847.        AHIDB_Realtime (ULONG *) - Modes which return TRUE for this fulfils
  848.            two criteria:
  849.            1) Calls to AHI_SetVol(), AHI_SetFreq() or AHI_SetSound() will be
  850.               preformed within (about) 10 ms if called from a PlayFunc Hook.
  851.            2) The PlayFunc Hook will be called at the specifed frequency.
  852.            If you don't use AHI's PlayFunc Hook, you must not use modes that
  853.            are not realtime. (Criterium 2 is not that obvious if you consider
  854.            a mode that renders the output to disk as a sample.)
  855.  
  856.        AHIDB_Bits (ULONG *) - The number of output bits (8, 12, 14, 16 etc).
  857.  
  858.        AHIDB_MaxChannels (ULONG *) - The maximum number of channels this mode
  859.            can handle.
  860.  
  861.        AHIDB_MinMixFreq (ULONG *) - The minimum mixing frequency supported.
  862.  
  863.        AHIDB_MaxMixFreq (ULONG *) - The maximum mixing frequency supported.
  864.  
  865.        AHIDB_Frequencies (ULONG *) - The number of different sample rates
  866.            available.
  867.  
  868.        AHIDB_FrequencyArg (ULONG) - Specifies which frequency
  869.            AHIDB_Frequency should return (see below). Range is 0 to
  870.            AHIDB_Frequencies-1 (including).
  871.            NOTE: ti_Data is NOT a pointer, but an ULONG.
  872.  
  873.        AHIDB_Frequency (ULONG *) - Return the frequency associated with the
  874.            index number specified with AHIDB_FrequencyArg (see above).
  875.  
  876.        AHIDB_IndexArg (ULONG) - AHIDB_Index will return the index which
  877.            gives the closest frequency to AHIDB_IndexArg
  878.            NOTE: ti_Data is NOT a pointer, but an ULONG.
  879.  
  880.        AHIDB_Index (ULONG *) - Return the index associated with the frequency
  881.            specified with AHIDB_IndexArg (see above).
  882.  
  883.        AHIDB_MaxPlaySamples (ULONG *) - Return the lowest number of sample
  884.            frames that must be present in memory when AHIST_DYNAMICSAMPLE
  885.            sounds are used. This number must then be scaled by Fs/Fm, where
  886.            Fs is the frequency of the sound and Fm is the mixing frequency.
  887.  
  888.        AHIDB_MaxRecordSamples (ULONG *) - Return the number of sample frames
  889.            you will recieve each time the RecordFunc is called.
  890.  
  891.        AHIDB_BufferLen (ULONG) - Specifies how many characters will be
  892.            copyed when requesting text attributes. Default is 0, which
  893.            means that AHIDB_Driver, AHIDB_Name, AHIDB_Author,
  894.            AHIDB_Copyright, AHIDB_Version and AHIDB_Annotation,
  895.            AHIDB_Input and AHIDB_Output will do nothing.
  896.  
  897.        AHIDB_Driver (STRPTR) - Name of driver (excluding path and
  898.            extention). 
  899.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  900.            will be stored. See AHIDB_BufferLen.
  901.  
  902.        AHIDB_Name (STRPTR) - Human readable name of this mode.
  903.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  904.            will be stored. See AHIDB_BufferLen.
  905.  
  906.        AHIDB_Author (STRPTR) - Name of driver author.
  907.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  908.            will be stored. See AHIDB_BufferLen.
  909.  
  910.        AHIDB_Copyright (STRPTR) - Driver copyright notice.
  911.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  912.            will be stored. See AHIDB_BufferLen
  913.  
  914.        AHIDB_Version (STRPTR) - Driver version string.
  915.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  916.            will be stored. See AHIDB_BufferLen.
  917.  
  918.        AHIDB_Annotation (STRPTR) - Annotation by driver author.
  919.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  920.            will be stored. See AHIDB_BufferLen.
  921.  
  922.        AHIDB_MinMonitorVolume (Fixed *)
  923.        AHIDB_MaxMonitorVolume (Fixed *) - Lower/upper limit for input
  924.            monitor volume, see AHI_ControlAudioA(). If both are 0.0,
  925.            the sound hardware does not have an input monitor feature.
  926.            If both are same, but not 0.0, the hardware always sends the
  927.            recorded sound to the outputs (at the given volume). (V2)
  928.  
  929.        AHIDB_MinInputGain (Fixed *)
  930.        AHIDB_MaxInputGain (Fixed *) - Lower/upper limit for input gain,
  931.            see AHI_ControlAudioA(). If both are same, there is no input
  932.            gain hardware. (V2)
  933.  
  934.        AHIDB_MinOutputVolume (Fixed *)
  935.        AHIDB_MaxOutputVolume (Fixed *) - Lower/upper limit for output
  936.            volume, see AHI_ControlAudioA(). If both are same, the sound
  937.            card does not have volume control. (V2)
  938.  
  939.        AHIDB_Inputs (ULONG *) - The number of inputs the sound card has.
  940.            (V2)
  941.  
  942.        AHIDB_InputArg (ULONG) - Specifies what AHIDB_Input should return
  943.            (see below). Range is 0 to AHIDB_Inputs-1 (including).
  944.            NOTE: ti_Data is NOT a pointer, but an ULONG. (V2)
  945.  
  946.        AHIDB_Input (STRPTR) - Gives a human readable string describing the
  947.            input associated with the index specified with AHIDB_InputArg
  948.            (see above). See AHI_ControlAudioA() for how to select one.
  949.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  950.            will be stored. See AHIDB_BufferLen. (V2)
  951.  
  952.        AHIDB_Outputs (ULONG *) - The number of outputs the sound card
  953.            has. (V2)
  954.  
  955.        AHIDB_OutputArg (ULONG) - Specifies what AHIDB_Output should return
  956.            (see below). Range is 0 to AHIDB_Outputs-1 (including)
  957.            NOTE: ti_Data is NOT a pointer, but an ULONG. (V2)
  958.  
  959.        AHIDB_Output (STRPTR) - Gives a human readable string describing the
  960.            output associated with the index specified with AHIDB_OutputArg
  961.            (see above). See AHI_ControlAudioA() for how to select one.
  962.            NOTE: ti_Data is a pointer to an UBYTE array where the name
  963.            will be stored. See AHIDB_BufferLen. (V2)
  964.  
  965.        If the requested information cannot be found, the variable will be not
  966.        be touched.
  967.  
  968.  
  969. RESULT
  970.        TRUE if everything went well.
  971.  
  972.  
  973. EXAMPLE
  974.  
  975.  
  976. NOTES
  977.  
  978.  
  979. BUGS
  980.  
  981.  
  982. SEE ALSO
  983.       AHI_NextAudioID(), AHI_BestAudioIDA()
  984.  
  985.  
  986.  
  987.  
  988. ahi.device/AHI_LoadSound
  989.  
  990. NAME
  991.        AHI_LoadSound -- prepare a sound for playback
  992.  
  993.  
  994. SYNOPSIS
  995.        error = AHI_LoadSound( sound, type, info, audioctrl );
  996.        D0                     D0:16  D1    A0    A2
  997.  
  998.        ULONG AHI_LoadSound( UWORD, ULONG, APTR, struct AHIAudioCtrl * );
  999.  
  1000.  
  1001. FUNCTION
  1002.        Defines an ID number for the sound and prepares it for playback.
  1003.  
  1004.  
  1005. INPUTS
  1006.        sound - The numeric ID to be used as a reference to this sound.
  1007.            The ID is a number greater or equal to 0 and less than what you
  1008.            specified with AHIA_Sounds when you called AHI_AllocAudioA().
  1009.        type - The type of the sound. Currently four types are supported:
  1010.            AHIST_SAMPLE - array of 8 or 16 bit samples. Note that the
  1011.                portion of memory where the sample is stored must NOT be
  1012.                altered until AHI_UnloadSound() has been called! This is
  1013.                because some audio drivers may wish to upload the sample
  1014.                to local RAM, or even change format of the sample data!
  1015.  
  1016.            AHIST_DYNAMICSAMPLE - array of 8 or 16 bit samples, which can be
  1017.                updated dynamically. Typically used to play data that is
  1018.                loaded from disk or calculated realtime.
  1019.                Avoid using this sound type as much as possible; it will
  1020.                use much more CPU power than AHIST_SAMPLE on a DMA/DSP
  1021.                sound card.
  1022.  
  1023.            AHIST_INPUT - The input from your sampler (not fully functional
  1024.                yet).
  1025.  
  1026.            AHIST_LOOP - Please don't use this type. I'm trying to decide if
  1027.                I should keep the loop support or not. For now, use 
  1028.                AHIA_SoundFunc (see AHI_AllocAudioA()) and handle the loops
  1029.                yourself.
  1030.  
  1031.        info - Depends on type:
  1032.            AHIST_SAMPLE - A pointer to a struct AHISampleInfo, filled with:
  1033.                ahisi_Type - Format of samples (only two supported).
  1034.                    AHIST_M8S: Mono, 8 bit signed (BYTEs).
  1035.                    AHIST_M8U: Mono, 8 bit unsigned (UBYTEs). Avoid using
  1036.                        this type if possible!
  1037.                    AHIST_M16S: Mono, 16 bit signed (WORDs).
  1038.                ahisi_Address - Address to the sample array.
  1039.                ahisi_Length - The size of the array, in samples.
  1040.                Don't even think of setting ahisi_Address to 0 and
  1041.                ahisi_Length to 0xffffffff as you can do with
  1042.                AHIST_DYNAMICSAMPLE! Very few DMA/DSP cards has 4 GB onboard
  1043.                RAM...
  1044.  
  1045.            AHIST_DYNAMICSAMPLE A pointer to a struct AHISampleInfo, filled
  1046.                as described above (AHIST_SAMPLE).
  1047.                If ahisi_Address is 0 and ahisi_Length is 0xffffffff
  1048.                AHI_SetSound() can take the real address of an 8 bit sample
  1049.                to be played as offset argument. Unfortunately, this does not
  1050.                work for 16 bit samples.
  1051.  
  1052.            AHIST_INPUT - Allways set info to NULL.
  1053.                Note that AHI_SetFreq() may only be called with AHI_MIXFREQ
  1054.                for this sample type.
  1055.  
  1056.            AHIST_LOOP - Temporary (?) removed.
  1057.  
  1058.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1059.  
  1060.  
  1061. RESULT
  1062.        An error code, defined in <devices/ahi.h>.
  1063.  
  1064.  
  1065. EXAMPLE
  1066.  
  1067.  
  1068. NOTES
  1069.        There is no need to place a sample array in Chip memory.
  1070.        SoundFunc will be called in the same manner as Paula interrups
  1071.        occur; when the device has updated its internal variables and can
  1072.        accept new commands. Note that SoundFunc will be called for every
  1073.        loop played in a multi-loop sound.
  1074.  
  1075.  
  1076. BUGS
  1077.        AHIST_INPUT does not fully work yet.
  1078.  
  1079.  
  1080. SEE ALSO
  1081.        AHI_UnloadSound(), AHI_SetEffect(), AHI_SetFreq(), AHI_SetSound(),
  1082.        AHI_SetVol(), <devices/ahi.h>
  1083.  
  1084.  
  1085.  
  1086.  
  1087. ahi.device/AHI_NextAudioID
  1088.  
  1089. NAME
  1090.        AHI_NextAudioID -- iterate current audio mode identifiers
  1091.  
  1092.  
  1093. SYNOPSIS
  1094.        next_ID = AHI_NextAudioID( last_ID );
  1095.        D0                         D0
  1096.  
  1097.        ULONG AHI_NextAudioID( ULONG );
  1098.  
  1099.  
  1100. FUNCTION
  1101.        This function is used to itereate through all current AudioIDs in
  1102.        the audio database.
  1103.  
  1104.  
  1105. INPUTS
  1106.        last_ID - previous AudioID or AHI_INVALID_ID if beginning iteration.
  1107.  
  1108.  
  1109. RESULT
  1110.        next_ID - subsequent AudioID or AHI_INVALID_ID if no more IDs.
  1111.  
  1112.  
  1113. EXAMPLE
  1114.  
  1115.  
  1116. NOTES
  1117.  
  1118.  
  1119. BUGS
  1120.  
  1121.  
  1122. SEE ALSO
  1123.       AHI_GetAudioAttrsA(), AHI_BestAudioIDA()
  1124.  
  1125.  
  1126.  
  1127.  
  1128. ahi.device/AHI_SetEffect
  1129.  
  1130. NAME
  1131.        AHI_SetEffect -- set effect
  1132.  
  1133.  
  1134. SYNOPSIS
  1135.        AHI_SetEffect( effect, audioctrl );
  1136.                       A0      A2
  1137.  
  1138.        void AHI_SetEffect( APTR, struct AHIAudioCtrl * );
  1139.  
  1140.  
  1141. FUNCTION
  1142.        Selects an effect to be used, described by a structure.
  1143.  
  1144.  
  1145. INPUTS
  1146.        effect - A pointer to an effect data structure, as defined in
  1147.            <devices/ahi.h>. The following effects are defined:
  1148.            AHIET_MASTERVOLUME - Changes the volume for all channels. Can
  1149.                also be used to boost volume over 100%.
  1150.            AHIET_OUTPUTBUFFER - Gives READ-ONLY access to the mixed output.
  1151.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1152.  
  1153.  
  1154. EFFECTS
  1155.        AHIET_MASTERVOLUME - Effect is a struct AHIEffMasterVolume, with
  1156.            ahiemv_Volume set to the desired volume. The range is 0 to
  1157.            (channels/hardware channel). Assume you have 4 channels in
  1158.            mono mode. The range is then 0.0 to 4.0. The range is the same
  1159.            if the mode is stereo with panning. However, assume you have 4
  1160.            channels with a stereo mode *without* panning. Then you have two
  1161.            channels to the left and two to the right => range is 0.0 - 2.0.
  1162.            Setting the volume outside the range will give an unpredictable
  1163.            result!
  1164.            Note that AHIET_MASTERVOLUME is digital master volume, which means
  1165.            that it does not affect AHIET_INPUTMONITORVOLUME at all.
  1166.  
  1167.        AHIET_OUTPUTBUFFER - Effect is a struct AHIEffOutputBuffer, with
  1168.            ahieob_Func pointing to a hook that will be called with the
  1169.            following parameters:
  1170.                A0 - (struct Hook *)
  1171.                A2 - (struct AHIAudioCtrl *)
  1172.                A1 - (struct AHIEffOutputBuffer *)
  1173.            The information you are looking for then is in ahieob_Type,
  1174.            ahieob_Buffer and ahieob_Length. Always check ahieob_Type!
  1175.            ahieob_Length is neither in bytes nor samples, but SAMPLE FRAMES.
  1176.  
  1177.        NOTE! To turn off an effect, call again with ahie_Effect OR:ed
  1178.        with AHIET_CANCEL. For example, it is NOT correct to disable
  1179.        the AHIET_MASTERVOLUME effect by setting ahiemv_Volume to 1.0!
  1180.  
  1181.  
  1182. RESULT
  1183.  
  1184.  
  1185. EXAMPLE
  1186.  
  1187.  
  1188. NOTES
  1189.  
  1190.  
  1191. BUGS
  1192.  
  1193.  
  1194. SEE ALSO
  1195.        AHI_SetFreq(), AHI_SetSound(), AHI_SetVol(), AHI_LoadSound(),
  1196.        <devices/ahi.h>
  1197.  
  1198.  
  1199.  
  1200.  
  1201. ahi.device/AHI_SetFreq
  1202.  
  1203. NAME
  1204.        AHI_SetFreq -- set frequency for a channel
  1205.  
  1206.  
  1207. SYNOPSIS
  1208.        AHI_SetFreq( channel, freq, audioctrl, flags );
  1209.                     D0:16    D1    A2         D2
  1210.  
  1211.        void AHI_SetFreq( UWORD, ULONG, struct AHIAudioCtrl *, ULONG );
  1212.  
  1213.  
  1214. FUNCTION
  1215.        Sets the playback frequency for a channel.
  1216.  
  1217.  
  1218. INPUTS
  1219.        channel - The channel to set playback frequency for.
  1220.        freq - The playback frequency in Herz. Can also be AHI_MIXFREQ,
  1221.            is the current mixing frequency (only usable with AHIST_INPUT
  1222.            sounds), or 0 to temporary stop the sample (it will restart at
  1223.            the same point when its frequency changed).
  1224.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1225.        flags - Only one flag is defined
  1226.            AHISB_IMM - Set this bit if this command should take effect
  1227.                immediately. If this bit is not set, the command will not
  1228.                take effect until the current sound is finished. MUST be
  1229.                set if not called from a SoundFunc.
  1230.  
  1231.  
  1232. RESULT
  1233.  
  1234.  
  1235. EXAMPLE
  1236.  
  1237.  
  1238. NOTES
  1239.        It is safe to call this function from an interrupt.
  1240.  
  1241.  
  1242. BUGS
  1243.        Freq is limited to 262143 Hz.
  1244.  
  1245.  
  1246. SEE ALSO
  1247.        AHI_SetEffect(),  AHI_SetSound(), AHI_SetVol(), AHI_LoadSound()
  1248.  
  1249.  
  1250.  
  1251.  
  1252. ahi.device/AHI_SetSound
  1253.  
  1254. NAME
  1255.        AHI_SetSound -- set what sound to play for a channel
  1256.  
  1257.  
  1258. SYNOPSIS
  1259.        AHI_SetSound( channel, sound, offset, length, audioctrl, flags );
  1260.                       D0:16   D1:16   D2      D3      A2         D4
  1261.  
  1262.        void AHI_SetSound( UWORD, UWORD, ULONG, LONG,
  1263.                           struct AHIAudioCtrl *, ULONG );
  1264.  
  1265.  
  1266. FUNCTION
  1267.        Sets a sound to be played on a channel.
  1268.  
  1269.  
  1270. INPUTS
  1271.        channel - The channel to set sound for.
  1272.        sound - Sound to be played, or AHI_NOSOUND to turn the channel off.
  1273.        offset - Only available if the sound type is AHIST_SAMPLE or
  1274.            AHIST_DYNAMICSAMPLE. Must be 0 otherwise.
  1275.            Specifies an offset (in samples) where the playback will begin.
  1276.            If you wish to play the whole sound, set offset to 0.
  1277.        length - Only available if the sound type is AHIST_SAMPLE or
  1278.            AHIST_DYNAMICSAMPLE. Must be 0 otherwise.
  1279.            Specifies how many samples that should be played. If you
  1280.            wish to play the whole sound forwards, set offset to 0 and length
  1281.            to either 0 or the length of the sample array. You may not set
  1282.            length to 0 if offset is not 0! To play a sound backwards, just
  1283.            set length to a negative number.
  1284.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1285.        flags - Only one flag is defined
  1286.            AHISB_IMM - Set this bit if this command should take effect
  1287.                immediately. If this bit is not set, the command will not
  1288.                take effect until the current sound is finished. MUST be
  1289.                set if not called from a SoundFunc.
  1290.  
  1291.  
  1292. RESULT
  1293.  
  1294.  
  1295. EXAMPLE
  1296.  
  1297.  
  1298. NOTES
  1299.        It is safe to call this function from an interrupt.
  1300.        If offset or length is not zero, make sure you do not exceed the
  1301.        sample limits.
  1302.  
  1303.  
  1304. BUGS
  1305.  
  1306.  
  1307. SEE ALSO
  1308.        AHI_SetEffect(),  AHI_SetFreq(), AHI_SetVol(), AHI_LoadSound()
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314. ahi.device/AHI_SetVol
  1315.  
  1316. NAME
  1317.        AHI_SetVol -- set volume and stereo panning for a channel
  1318.  
  1319.  
  1320. SYNOPSIS
  1321.        AHI_SetVol( channel, volume, pan, audioctrl, flags );
  1322.                    D0:16    D1      D2   A2         D3
  1323.  
  1324.        void AHI_SetVol( UWORD, Fixed, sposition, struct AHIAudioCtrl *,
  1325.                         ULONG );
  1326.  
  1327.  
  1328. FUNCTION
  1329.        Changes the volume and stereo panning for a channel.
  1330.  
  1331.  
  1332. INPUTS
  1333.        channel - The channel to set volume for.
  1334.        volume - The desired volume. Fixed is a LONG fixed-point value with
  1335.            16 bits to the left of the point and 16 to the right
  1336.            (typedef LONG Fixed; from IFF-8SVX docs).
  1337.            Maximum volume is 1.0 (0x10000L) and 0.0 (0x0L) will turn off
  1338.            this channel. Note: The sound will continue to play, but you
  1339.            wont hear it. To stop a sound completely, use AHI_SetSound().
  1340.        pan - The desired panning. sposition is the same as Fixed
  1341.            (typedef Fixed sposition; from IFF-8SVX.PAN docs).
  1342.            1.0 (0x10000L) means that the sound is panned all the way to
  1343.            the right, 0.5 (0x8000L) means the sound is centered and 0.0
  1344.            (0x0L) means that the sound is panned all the way to the left.
  1345.            Try to set Pan to the 'correct' value even if you know it has no
  1346.            effect. For example, if you know you use a mono mode, set pan to
  1347.            0.5 even if it does not matter.
  1348.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1349.        flags - Only one flag is defined
  1350.            AHISB_IMM - Set this bit if this command should take effect
  1351.                immediately. If this bit is not set, the command will not
  1352.                take effect until the current sound is finished. MUST be
  1353.                set if not called from a SoundFunc.
  1354.  
  1355.  
  1356. RESULT
  1357.  
  1358.  
  1359. EXAMPLE
  1360.  
  1361.  
  1362. NOTES
  1363.        It is safe to call this function from an interrupt.
  1364.  
  1365.  
  1366. BUGS
  1367.  
  1368.  
  1369. SEE ALSO
  1370.        AHI_SetEffect(), AHI_SetFreq(), AHI_SetSound(), AHI_LoadSound()
  1371.        
  1372.  
  1373.  
  1374.  
  1375.  
  1376. ahi.device/AHI_UnloadSound
  1377.  
  1378. NAME
  1379.        AHI_UnloadSound -- discard a sound
  1380.  
  1381.  
  1382. SYNOPSIS
  1383.        AHI_UnloadSound( sound, audioctrl );
  1384.                         D0:16  A2
  1385.  
  1386.        void AHI_UnloadSound( UWORD, struct AHIAudioCtrl * );
  1387.  
  1388.  
  1389. FUNCTION
  1390.        Tells 'ahi.device' that this sound will not be used anymore.
  1391.  
  1392.  
  1393. INPUTS
  1394.        sound - The ID of the sound to unload.
  1395.        audioctrl - A pointer to an AHIAudioCtrl structure.
  1396.  
  1397.  
  1398. RESULT
  1399.  
  1400.  
  1401. EXAMPLE
  1402.  
  1403.  
  1404. NOTES
  1405.  
  1406.  
  1407. BUGS
  1408.  
  1409.  
  1410. SEE ALSO
  1411.        AHI_LoadSound()
  1412.  
  1413.  
  1414.  
  1415.