Amiga ISO Collection/AmigaMiscModsCD3.iso/_PROGRAMME/PLAYER/SINGLEFORMAT/MagicMOD.lha/PTReplay.doc

Text File | 1995-11-08 | 16.8 KB | 649 lines

TABLE OF CONTENTS

ptreplay.library/PTFade
ptreplay.library/PTFreeMod
ptreplay.library/PTGetChan
ptreplay.library/PTGetPri
ptreplay.library/PTGetSample
ptreplay.library/PTInstallBits
ptreplay.library/PTLoadModule
ptreplay.library/PTOffChannel
ptreplay.library/PTOnChannel
ptreplay.library/PTPatternData
ptreplay.library/PTPatternPos
ptreplay.library/PTPause
ptreplay.library/PTPlay
ptreplay.library/PTResume
ptreplay.library/PTSetPos
ptreplay.library/PTSetPri
ptreplay.library/PTSetupMod
ptreplay.library/PTSetVolume
ptreplay.library/PTSongLen
ptreplay.library/PTSongPattern
ptreplay.library/PTSongPos
ptreplay.library/PTStartFade
ptreplay.library/PTStop
ptreplay.library/PTUnloadModule
ptreplay.library/PTFade                               ptreplay.library/PTFade

   NAME
        PTFade -- Let a module "slide away" before it's stopped (V2)

   SYNOPSIS
        PTFade(module,speed)
                A0     D0

        void PTFade(struct Module *, UBYTE);

   FUNCTION
        This function does smooth vol slidedown until volume reaches zero,
        then the module is stoped and the function returns. The speed is
        given in the number of "vblanks" (ie CIA timeouts because it uses
        CIA timing instead of vblank timing) between each step.

   INPUTS
        module - module that is to be stoped.
        speed - fading speed.

   SEE ALSO
        PTStartFade()

ptreplay.library/PTFreeMod                         ptreplay.library/PTFreeMod

   NAME
        PTFreeMod -- Deallocates a module create with PTSetupMod. (V4)

   SYNOPSIS
        PTFreeMod(Module)
                  A0

        void PTFreeMod(struct Module *);

   FUNCTION
        This function will free all memory allocated by the PTSetupMod
        function.

   INPUTS
        Module - a module returned by PTSetupMod().

   SEE ALSO
        PTSetupMod()

ptreplay.library/PTGetChan                         ptreplay.library/PTGetChan

   NAME
        PTGetChan -- Return wich channels ptreplay owns. (V6)

   SYNOPSIS
        Chans=PTGetChan()
        D0

        BYTE PTGetChan(void);

   FUNCTION
        This function returns an array there bit 0 is set if it owns channel
        0, bit 1 is set if it owns channel 1 and so on.

   RESULT
        Chans - An bitarray telling you wich channel it owns.

   SEE ALSO

ptreplay.library/PTGetPri                           ptreplay.library/PTGetPri

   NAME
        PTGetPri -- Return the priority currently used. (V5)

   SYNOPSIS
        Pri=PTSetPri()
        D0
        BYTE PTSetPri(void);

   FUNCTION
        This function returnes the current priority on wich ptreplay hold
        it's channels.

   RESULT
        Pri - The priority currently used by ptreplay.

   SEE ALSO
        PTSetPri()

ptreplay.library/PTGetSample                     ptreplay.library/PTGetSample

   NAME
        PTGetSample -- Return info on a sample. (V6)

   SYNOPSIS
        Sam=PTGetSample(Module,Num);
        D0              A0     D0

        struct PTSample *PTGetSample(struct Module *,WORD);

   FUNCTION
        This function collects info about the given sample-number.

        it returns the folowing structure:
        struct PTSample
        {
            UBYTE Name[22];    /* Null terminated string with samplename */
            UWORD Length;      /* Sample length in words */
            UBYTE FineTune;    /* FineTune of sample in lower 4 bits */
            UBYTE Volume;      /* Volume of sample */
            UWORD Repeat;      /* Repeat start in number of words */
            UWORD Replen;      /* Repeat length in number of words */
        };

   INPUTS
        Module - Pointer to a loaded module
        Num    - Number of the sample you whant info about. MUST BE 0-31

   RESULT
        Sam - Info about the given sample.

   SEE ALSO

ptreplay.library/PTInstallBits                 ptreplay.library/PTInstallBits

   NAME
        PTInstallBits -- Defines what to be signaled at and how (V4)

   SYNOPSIS
        PTInstallBits(Module, Restart, Pos, Row, Fade);
                      A0      D0       D1   D2   D3

        void PTInstallBits(struct Module *, BYTE, BYTE, BYTE, BYTE);

   FUNCTION
        This function is used to inform ptreplay which signals to send to
        this task at the given positions. Currently it can only be set up to
        signal one task/module (the one calling this function) this may
        however change in future. A signalbit of -1 tells ptreplay not to
        signal you at that specific location.

   INPUTS
        Module - module to use the given signals
        Restart - Bit to set when a module restarts from beginning or -1 for
            no signal.
        Pos - Bit to set when moving to next position or -1 for no signal
        Row - Bit to set when moving to next row in pattern or -1 for no
            signal.
        Fade - Bit to set when PTStartFade is done and have stoped module or
            -1 for no signal.

   EXAMPLE
        /* This will set signalbit 4 when the module restarts */
        PTInstallBits(Module, 4, -1, -1, -1);

        /* This will set signalbit 0 when startfade has stopped the module */
        PTInstallBits(Module, -1, 1, -1, 0);

   SEE ALSO
        PTStartFade()

ptreplay.library/PTLoadModule                   ptreplay.library/PTLoadModule

   NAME
        PTLoadModule -- Load a module.

   SYNOPSIS
        module=PTLoadModule(name)
          D0                A0

        struct module *PTLoadModule(STRPTR);

   FUNCTION
        The named file is loaded into chip-mem and if it's identified as an
        protracker module, a module control structure is created and then
        returned to you for usage in the other functions like PTPlay

   INPUTS
        name - name of a module file.

   RESULT
        module - a pointer to a module control structure or NULL if the
            module couldn't be loaded.

   SEE ALSO
        PTSetupMod(), PTUnloadModule()

ptreplay.library/PTOffChannel                   ptreplay.library/PTOffChannel

   NAME
        PTOffChannel -- Turns off one or more channels. (V5)

   SYNOPSIS
        PTStartFade(Module, Channel)
                    A0      D0

        void PTStartFade(struct Module *, BYTE);

   FUNCTION
        This function is used to turn one or more channels off in order to
        stop ptreplay producing sound for that channel. Note that this isn't
        a nested command and turning off a channel that is already off will
        give you strange results and is _not_ recomended.

   INPUTS
        Module - Module to select channels for.
        Channel - Channels to be turned off.

   RESULT

   EXAMPLE

   NOTES

   BUGS
        Turning a channel off will not release it to be used by other
        programms via audio.device.

   SEE ALSO
        PTOnChannel()

ptreplay.library/PTOnChannel                     ptreplay.library/PTOnChannel

   NAME
        PTOnChannel -- Turns on one or more channels. (V5)

   SYNOPSIS
        PTStartFade(Module, Channel)
                    A0      D0

        void PTStartFade(struct Module *, BYTE);

   FUNCTION
        This function is used to turn one or more channels on in order for
        ptreplay to produce sound for that channel. Note that this isn't
        a nested command and turning on a channel that is already on will
        give you strange results.

   EXAMPLE
       ;Turn on all 4 channels
       PTOnChannel(Mod, $f);

       ;Turn on channel 0,1 & 2
       PTOnChannel(Mod, &7);

   INPUTS
        Module - Module to select channels for.
        Channel - Channels to be turned on.

   SEE ALSO
        PTOffChannel()

ptreplay.library/PTPatternData                 ptreplay.library/PTPatternData

   NAME
        PTPatternData -- Returns the adress of specified pattern/row (V4)

   SYNOPSIS
        RowData=PTPatternData(Module, PatternNum, RowNum)
        D0                    A0      D0          D1

        APTR PTPatternData(struct Module *, UBYTE, UBYTE);

   FUNCTION
        This function returns a pointer to the given row in the specified
        pattern.

   INPUTS
        Module     - Pointer to the module you which to examine.
        PatternNum - The pattern (0-127) you want to examine.
        RowNum      - And finaly which row (0-63) to examine.

   RESULT
        RowData - A pointer to the given position

ptreplay.library/PTPatternPos                   ptreplay.library/PTPatternPos

   NAME
        PTPatternPos -- Returns the patternrow currently playing (V4)

   SYNOPSIS
        Row=PTPatternPos(module)
        D0               A0

        UBYTE PTPatternPos(struct Module *);

   FUNCTION
        Returns the row in the pattern that it is currently being played.

   INPUTS
        module - A module that is currently being played.

   RESULT
        Row - The row (0-63 $00-$40) that is being played.

ptreplay.library/PTPause                             ptreplay.library/PTPause

   NAME
        PTPause -- pauses a module.

   SYNOPSIS
        PTPause(module)
                A0

        void PTPause(struct Module *);

   FUNCTION
        Pause this module, remembering the position so that you can restart
        it later. All sound is turned off.

   INPUTS
        module - pointer to module control structure.

   NOTES
        All channels are still allocated at the same priority after this
        functions has returned so it's vise to lower the priority to -128
        before calling this function.

   SEE ALSO
        PTResume()

ptreplay.library/PTPlay                               ptreplay.library/PTPlay

   NAME
        PTPlay -- Plays a module

   SYNOPSIS
        PTPlay(module)
                A0

        void PTPlay(struct Module *);

   FUNCTION
        Start playing the module from the beginning. If this module already
        was playing, it starts over from the beginning.

   INPUTS
        module - pointer to module control structure.

   BUGS
        It is not yet supported to call this function while another module
        is playing.
        If another module is playing, it will be stopped and this will be
        played instead. (V5)

   SEE ALSO
        PTStop()

ptreplay.library/PTResume                           ptreplay.library/PTResume

   NAME
        PTResume -- restarts a paused module.

   SYNOPSIS
        PTResume(module)
                 A0

        void PTResume(struct Module *);

   FUNCTION
        Resume playing this module, after it was paused. If it was not
        paused then nothing happens. Becasue PTPause&PTResume doesn't nest
        will the module continue after the first call to PTResume.

   INPUTS
        module - pointer to module control structure.

   SEE ALSO
        PTPause()

ptreplay.library/PTSetPos                           ptreplay.library/PTSetPos

   NAME
        PTSetPos -- Changes the position for a playing module. (V5)

   SYNOPSIS
        PTSetPos(Module, Pos)
                 A0      D0

        void PTSetPos(struct Module *, UBYTE);

   FUNCTION
        This function changes the position which we are playing to the new
        one.

   INPUTS
        Module - Module to change pos in.
        Pos - The new position 0 - SongLen-1

   SEE ALSO
        PTSongPos(), PTSongLen()

ptreplay.library/PTSetPri                           ptreplay.library/PTSetPri

   NAME
        PTSetPri -- Sets the priority that ptreplay should use. (V5)

   SYNOPSIS
        PTSetPri(Pri)
                 D0

        void PTSetPri(BYTE);

   FUNCTION
        This function changes the priority on wich ptreplay hold it's
        channels. It deafults to -128 and is also reset to -128 every time
        the library is closed (OpenCnt==NULL).

        NOTE for V6: Now the channels are completly freed when the library
        is closed.

   INPUTS
        Pri - The new priority

   SEE ALSO
        PTGetPri()

ptreplay.library/PTSetupMod                       ptreplay.library/PTSetupMod

   NAME
        PTSetupMod -- Creates a control structure for a loaded module. (V4)

   SYNOPSIS
        Module = PTSetupMod(LoadedMod);
        D0                  A0

        struct Module *PTSetupMod(APTR);

   FUNCTION
        This function will allocate a module control structure and intilize
        it using an already loaded module file in order to use in with
        ptreplay.

   INPUTS
        LoadedMod - An pointer to an already loaded module.

   RESULT
        Module - A module control structure ready to use.

   EXAMPLE
        /* This routine will do the same thing as PTLoadMod */
        BPTR File;
        APTR Mod;
        int Len;
        struct Module *Module;

        File=Open("mod.module",MODE_OLDFILE))
        Seek(File, 0l, OFFSET_END);
        Len=Seek(File, 0l, OFFSET_BEGINNING);

        Mod=AllocMem(Len, MEMF_CHIP);
        Read(File, Mod, Len);
        Close(File);
        Module=PTSetupMod(Mod);

   NOTES
        1. The module MUST already be located in chip mem.
        2. The module MUST be valid while the module is going to be used.
        Both may change in future.

   SEE ALSO
        PTFreeMod()

ptreplay.library/PTSetVolume                     ptreplay.library/PTSetVolume

   NAME
        PTSetVolume -- Sets the base volume (V3)

   SYNOPSIS
        PTSetVolume(module,volume)
                    A0     D0

        void PTSetVolume(struct Module *, UBYTE);

   FUNCTION
        This function will change the base volume that ptreplay uses to
        calculate the "real" volume for the specified module.

        The new volume is first multiplied by this value and then shifted
        right 6 steps.

   INPUTS
        module - pointer to module.
        speed - new volume  0-64 ($00-$40)

   SEE ALSO
        Fade(), StartFade().

ptreplay.library/PTSongLen                         ptreplay.library/PTSongLen

   NAME
        PTSongLen -- returns songlength (V4)

   SYNOPSIS
        Len=PTSongLen(module)
        d0            a0

        UBYTE PTSongLen(struct Module *);

   FUNCTION
        This funktion returns the length of the module in positions. This
        is the same value as Length in ProTracker and means that it will
        play until position Len-1.

   INPUTS
        module - The module whos length you which to now.

   RESULT
        Len - Number of positions in module

ptreplay.library/PTSongPattern                 ptreplay.library/PTSongPattern

   NAME
        PTSongPattern -- Returns pattern at a given position (V4)

   SYNOPSIS
        PatNum=PTSongPattern(module, pos)
        D0                   A0      D0

        UBYTE PTSongPattern(struct Module *,UWORD);

   FUNCTION
        Returns the pattern number at a given position.

   INPUTS
        Module - The module you want to examine
        Pos - The position (0-127) you want to examine.

   RESULT
        PatNum - A number (0-127) telling you which pattern is to be played.

ptreplay.library/PTSongPos                         ptreplay.library/PTSongPos

   NAME
        PTSongPos -- Gives you the current song position (V4)

   SYNOPSIS
        Pos=PTSongPos(module);
        d0            A0

        UBYTE PTSongPos(struct Module *)

   FUNCTION
        This function returns the position the module is curently playing.

   INPUTS
        module - pointer to a module that is playing.

   RESULT
        Pos - position 0 - (Length-1)

   SEE ALSO
        PTSetPos()

ptreplay.library/PTStartFade                     ptreplay.library/PTStartFade

   NAME
        PTStartFade -- Let a module fade-away before it's stopped (V4)

   SYNOPSIS
        PTStartFade(Module, Speed)
                    A0      D0

        void PTStartFade(struct Module *, UBYTE);

   FUNCTION
        This function will also do a smooth volume slidedown in the same way
        as PTFade does but it returns as soon as the fading has started
        instead of when it is done. Currently the only way to notice when
        the module is stoped is to setup a Fade bit using PTInstallBits and
        check for that bit.

   INPUTS
        Module - Module to be stoped.
        Speed - fading speed.

   SEE ALSO
        PTFade(), PTInstallBits()

ptreplay.library/PTStop                               ptreplay.library/PTStop

   NAME
        PTStop -- Stops a module that is playing.

   SYNOPSIS
        PTStop(module)
                A0

        void PTStop(struct Module *);

   FUNCTION
        Stop playing the given module. If it wasn't playing, nothing
        happens.

   INPUTS
        module - pointer to module control structure.

   SEE ALSO
        PTPlay(), PTFade()

ptreplay.library/PTUnloadModule               ptreplay.library/PTUnloadModule

   NAME
        PTUnloadModule -- Deallocates a loaded module.

   SYNOPSIS
        PTUnloadModule(module)
                        A0

        void PTUnloadModule(struct Module *);

   FUNCTION
        Deallocates a previsly loaded module, returning all it's resources
        to the system.

   INPUTS
        module - pointer to module control structure returned by LoadModule.

   BUGS
        Does not check that module is stopped. If you call this function on
        a module that is playing, you _will_ cause a System Failure. You
        have been warned.

   SEE ALSO
        PTFreeMod(), PTStop()