home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / mus / Maestix / maestix.doc < prev    next >
Text File  |  1995-06-26  |  17KB  |  517 lines
  1. TABLE OF CONTENTS
  2.  
  3. maestix.library/AllocMaestro
  4. maestix.library/FlushReceive
  5. maestix.library/FlushTransmit
  6. maestix.library/FreeMaestro
  7. maestix.library/GetStatus
  8. maestix.library/ReceiveData
  9. maestix.library/SetMaestro
  10. maestix.library/StartRealtime
  11. maestix.library/StopRealtime
  12. maestix.library/TransmitData
  13.  
  14. maestix.library/AllocMaestro                     maestix.library/AllocMaestro
  15.  
  16.    NAME
  17.         AllocMaestro -- Allocates the MaestroPro sound board (V35)
  18.  
  19.    SYNOPSIS
  20.         MaestroBase = AllocMaestro(TagList)
  21.             D0.l                     A0.l
  22.  
  23.         struct MaestroBase* AllocMaestro(struct TagItem*);
  24.  
  25.         MaestroBase = AllocMaestroTags(Tag1,...)
  26.  
  27.         struct MaestroBase* AllocMaestroTags(ULONG,...);
  28.  
  29.    FUNCTION
  30.         This function allocates the MaestroPro sound board and gives
  31.         exclusive access to the client.
  32.  
  33.         The default settings after AllocMaestro() are:
  34.  
  35.          - Input is INPUT_STD,
  36.          - Output is OUTPUT_BYPASS,
  37.          - Studio mode is turned off,
  38.          - Copy protection is turned off,
  39.          - Emphasis is turned off,
  40.          - Source is DAT,
  41.          - Rate is 48kHz,
  42.          - Validity is true,
  43.          - the UDBs are reset.
  44.  
  45.    INPUTS
  46.         TagList         -- Reserved for future options. Currently always
  47.                            NULL or a pointer to TAG_DONE.
  48.  
  49.    RESULTS
  50.         MaestroBase     -- MaestroBase structure (private) or NULL, if
  51.                            the board has already been allocated or is
  52.                            not present.
  53.  
  54.    NOTES
  55.         This function must be used from DOS process only!
  56.  
  57.    SEE ALSO
  58.         FreeMaestro()
  59.  
  60.    BUGS
  61.         This function cannot prevent the MacroSystem programs (MaestroBR
  62.         and Samplitude) from using MaestroPro, too.
  63.  
  64.         This function tries to detect if such a program is currently
  65.         using the board, and does not allow a second allocation. But
  66.         this try may fail, so be aware! Since some old Maestix failed
  67.         even in the case the board was not allocated, this test was
  68.         removed in V37. Use AllocMstx and FreeMstx to avoid this
  69.         problem.
  70.  
  71. maestix.library/FlushReceive                     maestix.library/FlushReceive
  72.  
  73.    NAME
  74.         FlushReceive -- Stops receiver and replies all messages (V36)
  75.  
  76.    SYNOPSIS
  77.         FlushReceive(MaestroBase)
  78.                           A0.l
  79.  
  80.         void FlushReceive(struct MaestroBase*);
  81.  
  82.    FUNCTION
  83.         This function stops the receiver.
  84.  
  85.         All messages sent to Maestix by ReceiveData() are replied.
  86.  
  87.    INPUTS
  88.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  89.  
  90.    RESULTS
  91.  
  92.    NOTES
  93.  
  94.    SEE ALSO
  95.         FlushTransmit(), ReceiveData()
  96.  
  97.    BUGS
  98.  
  99. maestix.library/FlushTransmit                   maestix.library/FlushTransmit
  100.  
  101.    NAME
  102.         FlushTransmit -- Stops transmission and replies all messages (V36)
  103.  
  104.    SYNOPSIS
  105.         FlushTransmit(MaestroBase)
  106.                           A0.l
  107.  
  108.         void FlushTransmit(struct MaestroBase*);
  109.  
  110.    FUNCTION
  111.         This function stops the transmitter.
  112.  
  113.         All messages sent to Maestix by TransmitData() are replied.
  114.  
  115.    INPUTS
  116.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  117.  
  118.    RESULTS
  119.  
  120.    NOTES
  121.  
  122.    SEE ALSO
  123.         FlushReceive(), TransmitData()
  124.  
  125.    BUGS
  126.  
  127. maestix.library/FreeMaestro                       maestix.library/FreeMaestro
  128.  
  129.    NAME
  130.         FreeMaestro -- Frees the MaestroPro sound board (V35)
  131.  
  132.    SYNOPSIS
  133.         FreeMaestro(MaestroBase)
  134.                         A0.l
  135.  
  136.         void FreeMaestro(struct MaestroBase*);
  137.  
  138.    FUNCTION
  139.         The client must use this function to free the MaestroPro when
  140.         he does not need it any more.
  141.  
  142.         All messages previously sent to Maestix will be replied. The
  143.         FIFOs are cleared, the board is reset and switches to bypass
  144.         mode.
  145.  
  146.    INPUTS
  147.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  148.  
  149.    RESULTS
  150.  
  151.    NOTES
  152.         This function must be used from DOS process only!
  153.  
  154.    SEE ALSO
  155.         AllocMaestro()
  156.  
  157.    BUGS
  158.  
  159. maestix.library/GetStatus                           maestix.library/GetStatus
  160.  
  161.    NAME
  162.         GetStatus -- Returns the current board status (V35)
  163.  
  164.    SYNOPSIS
  165.         Status = GetStatus(MaestroBase,InfoType)
  166.          D0.l                  A0.l      D0.l
  167.  
  168.         ULONG GetStatus(struct MaestroBase*,ULONG);
  169.  
  170.    FUNCTION
  171.         The status fitting to the InfoType will be returned.
  172.  
  173.    INPUTS
  174.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  175.         InfoType        -- type code (MSTAT_...) of the status value
  176.                            that you require.
  177.  
  178.    RESULTS
  179.         Status          -- the result of the status query.
  180.  
  181.    NOTES
  182.         The following info types are existing:
  183.  
  184.         MSTAT_TFIFO     -- (ULONG) status of transmitter FIFO
  185.                            - FIFO_Off     -> transmitter is off
  186.                            - FIFO_Running -> transmission is running
  187.                            - FIFO_Error   -> an error occured since
  188.                                              last query
  189.  
  190.         MSTAT_RFIFO     -- (ULONG) status of receiver FIFO
  191.                            - FIFO_Off     -> receiver is off
  192.                            - FIFO_Running -> receiver is running
  193.                            - FIFO_Error   -> an error occured since
  194.                                              last query
  195.  
  196.         MSTAT_Signal    -- (BOOL) checks the signal at the current
  197.                            INPUT. FALSE if there is no signal.
  198.  
  199.         MSTAT_Emphasis  -- (BOOL) returns TRUE if the input signal
  200.                            has been recorded using emphasis.
  201.  
  202.         MSTAT_DATsrc    -- (BOOL) returns TRUE if the data source is
  203.                            a DAT or DCC recorder.
  204.  
  205.         MSTAT_CopyProh  -- (BOOL) returns TRUE if copy protection is
  206.                            requested from source. It is not possible
  207.                            to detect if it is an original or a copy!
  208.  
  209.         MSTAT_Rate      -- (ULONG) returns input rate.
  210.  
  211.         MSTAT_UDB       -- (UBYTE) [V37] returns the current UDBs.
  212.  
  213.    SEE ALSO
  214.  
  215.    BUGS
  216.  
  217. maestix.library/ReceiveData                       maestix.library/ReceiveData
  218.  
  219.    NAME
  220.         ReceiveData -- Receives data into a message (V35)
  221.  
  222.    SYNOPSIS
  223.         ReceiveData(MaestroBase,DataMessage)
  224.                        A0.l         A1.l
  225.  
  226.         void ReceiveData(struct MaestroBase*,struct DataMessage*)
  227.  
  228.    FUNCTION
  229.         The client has to fill out a DataMessage structure with a
  230.         reply port, a pointer to a data buffer and the size of this
  231.         buffer.
  232.  
  233.         This message is queued internally. If the receiver has not
  234.         been started yet, this function will activate it.
  235.  
  236.         The buffer space get filled with the incoming data and will
  237.         be replied to the declared reply port when the space has been
  238.         filled completely.
  239.  
  240.         If there are no more messages in the queue, the receiver
  241.         will be stopped automatically, and an error is reported.
  242.  
  243.         The buffer is filled with signed words. The first word always
  244.         belongs to the left channel, the second to the right, and so
  245.         on.
  246.  
  247.    INPUTS
  248.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  249.         DataMessage     -- DataMessage structure to a system message
  250.                            with a pointer to a buffer space for
  251.                            incoming data.
  252.  
  253.    RESULTS
  254.  
  255.    NOTES
  256.         The buffer space must be public memory. Its address must be
  257.         longword aligned, its length must be aligned to 1024 and the
  258.         size should be big enough (at least 10Kbyte).
  259.  
  260.         A realtime FX must be stopped before!
  261.  
  262.    SEE ALSO
  263.         TransmitData(), FlushReceive(), StopRealtime()
  264.  
  265.    BUGS
  266. maestix.library/SetMaestro                         maestix.library/SetMaestro
  267.  
  268.    NAME
  269.         SetMaestro -- Sets the MaestroPro parameters (V35)
  270.  
  271.    SYNOPSIS
  272.         SetMaestro(MaestroBase,TagList)
  273.                       A0.l       A1.l
  274.  
  275.         void SetMaestro(struct MaestroBase*,struct TagItem*);
  276.  
  277.         SetMaestroTags(MaestroBase,Tag1,...)
  278.  
  279.         void SetMaestroTags(struct MaestroBase*,ULONG,...);
  280.  
  281.    FUNCTION
  282.         The board parameters are changed by the provided tags.
  283.  
  284.    INPUTS
  285.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  286.         TagList         -- Tag list with the changes to be done
  287.  
  288.    RESULTS
  289.  
  290.    TAGS
  291.         MTAG_Input      -- (ULONG) selects the input that shall be used.
  292.                            Default is INPUT_STD, which is the input
  293.                            selected by SetMstx. INPUT_OPTICAL and
  294.                            INPUT_COAXIAL select the corresponding input.
  295.                            INPUT_SRC48K selects the internal 48kHz
  296.                            source.
  297.  
  298.         MTAG_Output     -- (ULONG) selects the data source for the
  299.                            MaestroPro output. Default is OUTPUT_BYPASS
  300.                            which leads the incoming data directly to the
  301.                            output. OUTPUT_INPUT decodes the input signal
  302.                            and encodes it with new channel status bits and
  303.                            user data bits. OUTPUT_FIFO encodes the
  304.                            transferred data to output.
  305.  
  306.         MTAG_SetCSB     -- (ULONG) the 32 bit will be put into the channel
  307.                            status bits directly. This tag should be used
  308.                            only exceptional.
  309.  
  310.         MTAG_SetUDB     -- (ULONG) the 32 bit will be put into the user
  311.                            data bits.
  312.  
  313.         MTAG_Studio     -- (BOOL) the studio mode is selected if this
  314.                            tag is TRUE, otherwise the custom mode is
  315.                            selected. Defaults to FALSE.
  316.  
  317.         MTAG_CopyProh   -- (ULONG) CPROH_OFF turns the copy protection
  318.                            off. CPROH_ON enables the copy protection,
  319.                            but one single digital copy can be made.
  320.                            CPROH_PROHIBIT turns the copy protection on;
  321.                            the signal cannot be recorded. CPROH_INPUT
  322.                            turns the copy protection on or off
  323.                            corresponding to the input signal. Default
  324.                            is CPROH_OFF.
  325.  
  326.         MTAG_Emphasis   -- (ULONG) EMPH_OFF turns emphasis off.
  327.                            EMPH_50us (= EMPH_ON) turns standard emphasis
  328.                            on. When using studio mode, EMPH_CCITT and
  329.                            EMPH_MANUAL can be selected, too. EMPH_INPUT
  330.                            chooses the emphasis corresponding to the
  331.                            input signal. Default is EMPH_OFF.
  332.  
  333.         MTAG_Source     -- (ULONG) selects the source category code.
  334.                            Default is SRC_DAT. Other codes are SRC_DSR,
  335.                            SRC_CD, SRC_ADCONV and SRC_INSTR. SRC_INPUT
  336.                            selects SRC_DAT or SRC_CD, corresponding to
  337.                            the input signal.
  338.  
  339.         MTAG_Rate       -- (ULONG) selects the rate. RATE_48000 is
  340.                            default, RATE_44100, RATE_32000 and
  341.                            RATE_48000MANU are possible, too. RATE_INPUT
  342.                            chooses a rate corresponding to the input
  343.                            signal.
  344.  
  345.         MTAG_Validity   -- (BOOL) TRUE if the output signal is valid,
  346.                            otherwise FALSE. Most receivers do not react
  347.                            if MTAG_Validity is FALSE.
  348.  
  349.         MTAG_ResetUDB   -- if this tag occures, UDBs are reset and will
  350.                            not be put out any more.
  351.  
  352.         MTAG_ResetLSA   -- [V37] this tag clears the local sample address
  353.                            which is used in studio mode transfers only.
  354.  
  355.  
  356.    NOTES
  357.         Note that MTAG_Rate will only be transmitted in the channel
  358.         status bits and is completely independent to the rate that
  359.         MaestrPro uses for data transfer. MaestroPro is only capable
  360.         to generate a 48kHz rate (INPUT_SRC48K). If another rate is
  361.         required, it must be put to the choosen input.
  362.  
  363.         Some receivers do not accept the incoming signal if the
  364.         transmitted rate is not equal to the transfer rate.
  365.  
  366.     A DAT delay will be executed if the current input/output are
  367.     changed by MSTAG_Input and/or MSTAG_Output. Note that this
  368.     delay may wait up to 30 seconds!
  369.  
  370.         This function must be used from DOS process only!
  371.  
  372.    SEE ALSO
  373.  
  374.    BUGS
  375. maestix.library/StartRealtime                   maestix.library/StartRealtime
  376.  
  377.    NAME
  378.         StartRealtime -- Starts realtime FX (V38)
  379.  
  380.    SYNOPSIS
  381.         StartRealtime(MaestroBase,TagList)
  382.                           A0.l       A1.l
  383.  
  384.         void StartRealtime(struct MaestroBase*,struct TagItem*);
  385.  
  386.         StartRealtimeTags(MaestroBase,Tag1,...)
  387.  
  388.         void StartRealtimeTags(struct MaestroBase*,ULONG,...);
  389.  
  390.    FUNCTION
  391.         This function starts a realtime effect. Before that, the used
  392.         input and OUTPUT_FIFO should be selected.
  393.  
  394.    INPUTS
  395.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  396.         TagList         -- TagList with the effect parameter
  397.  
  398.    RESULTS
  399.  
  400.    TAGS
  401.         MTAG_Effect     -- (ULONG) selects one of the internal effects
  402.                            (default: RFX_Bypass). See include file for
  403.                            all available effects.
  404.         MTAG_A0         -- (APTR) effect parameter
  405.         MTAG_A1         -- (APTR) effect parameter
  406.         MTAG_D2         -- (APTR) effect parameter
  407.         MTAG_D3         -- (APTR) effect parameter
  408.         MTAG_CustomCall -- (APTR) pointer to a custom effect routine,
  409.                            written in highly optimized assembly!
  410.  
  411.    NOTES
  412.         The custom effect routine gets the following parameters:
  413.  
  414.                 -> D0.w -- left data word
  415.                 -> D1.w -- right data word
  416.                 -> D2.l -- see MTAG_D2
  417.                 -> D3.l -- see MTAG_D3
  418.                 -> D6.l -- scratch
  419.                 -> D7.l -- scratch
  420.                 -> A0.l -- see MTAG_A0
  421.                 -> A1.l -- see MTAG_A1
  422.                 -> A2.l -- return address to be JMPed to...
  423.  
  424.         The routine's results are:
  425.  
  426.                 <- D0.w -- new left data word
  427.                 <- D1.w -- new right data word
  428.  
  429.         The register D2 to D5 and A0 to A7 must not be changed!
  430.  
  431.         Use "JMP (A2)" to return from the effect routine. Don't use RTS.
  432.  
  433.         The effect routine must be in MEMF_PUBLIC memory. Note that a task
  434.         must not be necessarily in MEMF_PUBLIC memory! This routine should
  435.         be coded in high optimized assembly language.
  436.  
  437.         If the effect routine is too slow on the used processor, this
  438.         function will be stopped automatically, and MSTAT_TFIFO and
  439.         MSTAT_RFIFO result FIFO_Error.
  440.  
  441.    SEE ALSO
  442.         StopRealtime()
  443.  
  444.    BUGS
  445. maestix.library/StopRealtime                     maestix.library/StopRealtime
  446.  
  447.    NAME
  448.         StopRealtime -- Stops the realtime FX (V38)
  449.  
  450.    SYNOPSIS
  451.         StopRealtime(MaestroBase)
  452.                           A0.l
  453.  
  454.         void StopRealtime(struct MaestroBase*);
  455.  
  456.    FUNCTION
  457.         This function stops a realtime effect.
  458.  
  459.    INPUTS
  460.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  461.  
  462.    RESULTS
  463.  
  464.    NOTES
  465.         Before using TransmitData() or ReceiveData(), a currently running
  466.         realtime effect must be stopped by this function!
  467.  
  468.    SEE ALSO
  469.         StartRealtime()
  470.  
  471.    BUGS
  472. maestix.library/TransmitData                     maestix.library/TransmitData
  473.  
  474.    NAME
  475.         TransmitData -- Transmits data from a message (V35)
  476.  
  477.    SYNOPSIS
  478.         TransmitData(MaestroBase,DataMessage)
  479.                         A0.l        A1.l
  480.  
  481.         void TransmitData(struct MaestroBase*,struct DataMessage*);
  482.  
  483.    FUNCTION
  484.         The client has to fill out a DataMessage structure with a
  485.         reply port, a pointer to a data buffer and the size of this
  486.         buffer.
  487.  
  488.         This message is queued internally. If the transmitter has not
  489.         been started yet, this function will activate it.
  490.  
  491.         The buffer space will be put out and then be replied to the
  492.         declared reply port.
  493.  
  494.         If there are no more messages in the queue, the transmitter
  495.         will be stopped automatically, and an error is reported.
  496.  
  497.         The buffer contains signed words. The first word always belongs
  498.         to the left channel, the second to the right, and so on.
  499.  
  500.    INPUTS
  501.         MaestroBase     -- MaestroBase structure from AllocMaestro().
  502.         DataMessage     -- a system message containing a pointer to a
  503.                            buffer space for incoming data.
  504.  
  505.    RESULTS
  506.  
  507.    NOTES
  508.         The buffer space must be public memory. Its address must be
  509.         longword aligned, its length must be aligned to 1024 and the
  510.         size should be big enough (at least 10Kbyte).
  511.  
  512.    SEE ALSO
  513.         ReceiveData(), FlushTransmit(), StopRealtime()
  514.  
  515.    BUGS
  516.  
  517.