@database "SuperPlay_Ref_ENG"
@master "DH1:PRG/superplay-lib_IDY/autodocs/SuperPlay_Ref_ENG.doc"

@Node Main "SuperPlay_Ref_ENG.doc"
    @{" --background-- " Link "--background--"}
    @{" SPL_AllocHandle() " Link "SPL_AllocHandle()"}
    @{" SPL_FreeHandle() " Link "SPL_FreeHandle()"}
    @{" SPL_StopReplay() " Link "SPL_StopReplay()"}
    @{" SPL_FreeResources() " Link "SPL_FreeResources()"}
    @{" SPL_SuperPlay() " Link "SPL_SuperPlay()"}
    @{" SPL_SuperWrite() " Link "SPL_SuperWrite()"}
    @{" SPL_InitHandleAsDOS() " Link "SPL_InitHandleAsDOS()"}
    @{" SPL_InitHandleAsClip() " Link "SPL_InitHandleAsClip()"}
    @{" SPL_SetWriteType() " Link "SPL_SetWriteType()"}
    @{" SPL_GetErrorString() " Link "SPL_GetErrorString()"}
    @{" SPL_SetWriteName() " Link "SPL_SetWriteName()"}
    @{" SPL_FileInfoRequest() " Link "SPL_FileInfoRequest()"}
    @{" SPL_SetReqIOWindow() " Link "SPL_SetReqIOWindow()"}
    @{" SPL_ReadPlayData() " Link "SPL_ReadPlayData()"}
    @{" SPL_ContinueReplay() " Link "SPL_ContinueReplay()"}
    @{" SPL_FastForward() " Link "SPL_FastForward()"}
    @{" SPL_FastBackward() " Link "SPL_FastBackward()"}
    @{" SPL_GetSampleList() " Link "SPL_GetSampleList()"}
    @{" SPL_SetSampleList() " Link "SPL_SetSampleList()"}
    @{" SPL_GetFileType() " Link "SPL_GetFileType()"}
@EndNode

@Node "--background--" "superplay.library/--background--"

@{b}   VERSION@{ub}
        $VER: SuperPlay_Ref_ENG.doc V6.3 (3.4.97)

@{b}   COPYRIGHT@{ub}
         1995-97 by Andreas R. Kleinert. All rights reserved.

        - Feel free to translate this Doc-File into other languages. -

@{b}   GENERAL@{ub}
              Andreas R. Kleinert,
              Sandstrasse 1,
              D-57072 Siegen,
              Germany.

        EMail:  Fido             Andreas Kleinert 2:2457/350.18
                Usenet/InterNet  Andreas_Kleinert@superview.ftn.neckar-alb.de

          If nothing else works, try one of these Fido-InterNet gateways:

                Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
                Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)

@{b}   HISTORY@{ub}
        V2     bug-fixed ClipBoard-Support
               with the supplied SPObjects (ak)
        V3     created working combination of
               @{"SPL_SetSampleList()" Link "SPL_SetSampleList()"} and SuperWrite()
               calls (ak)
        V4     filetype recognition without loading (ak)
        V4.6   Autodoc format
               SetWriteName(): Correct type of write_name
               Change two SVL_ prefix to SPL_
               Add version behind NAME            (indy)
        V5.1   SetWriteName() parameter must be UBYTE * (ak)
        V6.1   most stable version for now (ak)
        V6.2   add "()" to function names in text for better autodocs
               support(indy)
        V6.3   bumped version
               updated copyright note
               updated email address list (ak)


@EndNode

@Node "SPL_AllocHandle()" "superplay.library/SPL_AllocHandle"

@{b}   NAME@{ub}
        SPL_AllocHandle  (V1)

@{b}   SYNOPSIS@{ub}

        APTR SPL_AllocHandle(APTR future)
        D0   -$1e            A1

@{b}   FUNCTION@{ub}

        Allocates a handle for accessing a Sample/Module via SPObjects.

@{b}   INPUT(S)@{ub}

        future - always NULL yet

@{b}   RESULT@{ub}

        A pointer to a new allocated Handle or NULL, if allocation failed.

@{b}   WARNING@{ub}

        Test, if the result was NULL, or not !

@{b}   SEE ALSO@{ub}

        @{"SPL_FreeResources()" Link "SPL_FreeResources()"}, @{"SPL_FreeHandle()" Link "SPL_FreeHandle()"}

@EndNode

@Node "SPL_FreeHandle()" "superplay.library/SPL_FreeHandle"

@{b}   NAME@{ub}
        SPL_FreeHandle  (V1)

@{b}   SYNOPSIS@{ub}

        VOID SPL_FreeHandle(APTR handle)
        D0   -$24           A1

@{b}   FUNCTION@{ub}

       Stops playing, frees all Resources and delocates a Handle, which has
       been allocated with @{"SPL_AllocHandle()" Link "SPL_AllocHandle()"} before.

@{b}   INPUT(S)@{ub}

        handle - a valid handle

@{b}   RESULT@{ub}

        -

@{b}   SEE ALSO@{ub}

        @{"SPL_AllocHandle()" Link "SPL_AllocHandle()"}, @{"SPL_StopReplay()" Link "SPL_StopReplay()"}, @{"SPL_FreeResources()" Link "SPL_FreeResources()"}

@EndNode

@Node "SPL_StopReplay()" "superplay.library/SPL_StopReplay"

@{b}   NAME@{ub}
        SPL_StopReplay  (V1)

@{b}   SYNOPSIS@{ub}

        VOID SPL_StopReplay(APTR handle)
        D0   -$2a           A1

@{b}   FUNCTION@{ub}

        Stops playing the Sample/Module, indentified by the handle.
        Some SPObjects support to continue the Sample/Module with
        @{"SPL_ContinueReplay()" Link "SPL_ContinueReplay()"} after calling SPL_StopReplay().

@{b}   INPUT(S)@{ub}

        handle - a valid handle

@{b}   RESULT@{ub}

        -

@{b}   SEE ALSO@{ub}

        @{"SPL_ContinueReplay()" Link "SPL_ContinueReplay()"}, @{"SPL_FreeResources()" Link "SPL_FreeResources()"}, @{"SPL_FreeHandle()" Link "SPL_FreeHandle()"}

@EndNode

@Node "SPL_FreeResources()" "superplay.library/SPL_FreeResources"

@{b}   NAME@{ub}
        SPL_FreeResources (V1)

@{b}   SYNOPSIS@{ub}

        VOID SPL_FreeResources(APTR handle)
        D0   -$30              A1

@{b}   FUNCTION@{ub}

        Frees all resources belonging to the specific Sample/Module,
        indentified by the handle, which are not needed to just replay it.
        Playing of the Sample/Module is not stopped and/or interrupted.

@{b}   INPUT(S)@{ub}

        handle - a valid handle

@{b}   RESULT@{ub}

        -

@{b}   SEE ALSO@{ub}

        @{"SPL_AllocHandle()" Link "SPL_AllocHandle()"}, @{"SPL_StopReplay()" Link "SPL_StopReplay()"}, @{"SPL_FreeHandle()" Link "SPL_FreeHandle()"}

@EndNode

@Node "SPL_SuperPlay()" "superplay.library/SPL_SuperPlay"

@{b}   NAME@{ub}
        SPL_SuperPlay  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_SuperPlay(APTR handle, char *filename)
        D0    -$36          A1           A2

@{b}   FUNCTION@{ub}

        Loads and plays the Sample/Module described by FileName.
        The handle is initialized and the fitting SPObject is opened
        and accessed for replaying the Sample/Module.

        Playing can be stopped either via full delocation of the handle
        or temporal interruption with @{"SPL_StopReplay()" Link "SPL_StopReplay()"}.

@{b}   INPUT(S)@{ub}

        handle   - a valid handle
        filename - a valid AmigaDOS FilePath and -Name

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_AllocHandle()" Link "SPL_AllocHandle()"}, @{"SPL_StopReplay()" Link "SPL_StopReplay()"}, @{"SPL_ContinueReplay()" Link "SPL_ContinueReplay()"},
        @{"SPL_FastForward()" Link "SPL_FastForward()"}, @{"SPL_FastBackward()" Link "SPL_FastBackward()"}, @{"SPL_FreeHandle()" Link "SPL_FreeHandle()"}

@EndNode

@Node "SPL_SuperWrite()" "superplay.library/SPL_SuperWrite"

@{b}   NAME@{ub}
        SPL_SuperWrite  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_SuperWrite(APTR handle, APTR source_handle)
        D0    -$3c           A1           A2

@{b}   FUNCTION@{ub}

        Usually a Sample/Module is loaded AND played via SPL_SuperPlay():
        No separate reading and playing calls are done.

        For writing - that means : converting - a Sample/Module, you
        have to use the following order :

        source_handle = SPL_AllocHandle(N);
        result        = SPL_ReadPlayData(source_handle, source_name);
        dest_handle   = SPL_AllocHandle(N);
        /* result     = SPL_InitHandleAsDOS(dest_handle, N); */ /* default */
        result        = SPL_SetWriteName(dest_handle, dest_name, N);
        result        = SPL_SetWriteType(dest_handle, dest_type, N);
        result        = SPL_SuperWrite(dest_handle, source_handle);
        SPL_FreeHandle(dest_handle);
        SPL_FreeHandle(source_handle);


        Also : Check the "result" value AFTER EACH function call (see
               Example SourceCodes) !

        All available values for dest_type can be found in the specific
        SPOBject-List in the SuperPlayBase.
        The values WILL change with every re-initialization of
        superplay.library, so update them with every new opening !

        If "source_handle" is NULL,
        it is checked, whether a SampleList has been set via
        "SPL_SetSampleList()", and then this SampleList is completely
        saved.

        It is suggested to use the old style for converting between
        FileFormats and the new style for saving single (self-created)
        SampleLists.

@{b}   INPUT(S)@{ub}

        handle        - a valid handle        (used for Write Access)
        source_handle - an other valid handle (used for Read Access)

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}



        @{"SPL_AllocHandle()" Link "SPL_AllocHandle()"}, @{"SPL_ReadPlayData()" Link "SPL_ReadPlayData()"}, @{"SPL_FreeHandle()" Link "SPL_FreeHandle()"}

@EndNode

@Node "SPL_InitHandleAsDOS()" "superplay.library/SPL_InitHandleAsDOS"

@{b}   NAME@{ub}
        SPL_InitHandleAsDOS (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_InitHandleAsDOS(APTR handle, APTR future)
        D0    -$42                A1           A2

@{b}   FUNCTION@{ub}

        Initializes a Handle for AmigaDOS access, so that the given
        AmigaDOS FileNames are used.
        Another possibility is sometimes to initialize Handles
        for ClipBoard Access (depending on the specific SPObject,
        e.g. IFF-8SVX).

@{b}   INPUT(S)@{ub}

        handle - a valid handle
        future - always NULL yet


@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_InitHandleAsClip()" Link "SPL_InitHandleAsClip()"}

@EndNode

@Node "SPL_InitHandleAsClip()" "superplay.library/SPL_InitHandleAsClip"

@{b}   NAME@{ub}
        SPL_InitHandleAsClip  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_InitHandleAsClip(APTR handle, APTR future)
        D0    -$48                 A1           A2

@{b}   FUNCTION@{ub}

        Initializes a Handle for ClipBoard access, so that the (possibly)
        given AmigaDOS FileNames are ignored.
        The nearly always used possibility is to initialize Handles
        for AmigaDOS Access (supported by ALL SPObjects).

@{b}   INPUT(S)@{ub}

        handle - a valid handle
        future - always NULL yet


@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_InitHandleAsDOS()" Link "SPL_InitHandleAsDOS()"}

@EndNode

@Node "SPL_SetWriteType()" "superplay.library/SPL_SetWriteType"

@{b}   NAME@{ub}
        SPL_SetWriteType  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_SetWriteType(APTR handle, ULONG write_type, APTR future)
        D0    -$4e             A1           A2                A3

@{b}   FUNCTION@{ub}

        Sets the write_type for a @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"} call.
        See description there and example SourceCodes for more and
        detailed information.

@{b}   INPUT(S)@{ub}

        handle     - a valid handle
        write_type - a valid temporary write_type code form the SPObject @{"List" Link "TEXT_INCLUDE:exec/lists.h/Main" 21}
        future     - always NULL yet


@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"}

@EndNode

@Node "SPL_GetErrorString()" "superplay.library/SPL_GetErrorString"

@{b}   NAME@{ub}
        SPL_GetErrorString  (V1)

@{b}   SYNOPSIS@{ub}

        char * SPL_GetErrorString(ULONG error_code)
        D0    -$54                A1

@{b}   FUNCTION@{ub}

        Returns the Error @{"Message" Link "TEXT_INCLUDE:exec/ports.h/Main" 48} for a specific Error Code, returned
        by any function of the superplay.library.

@{b}   INPUT(S)@{ub}

        error_code - any SPERR Error Code

@{b}   RESULT@{ub}

        read-only pointer to a SPERR Error String

@{b}   SEE ALSO@{ub}

        -

@EndNode

@Node "SPL_SetWriteName()" "superplay.library/SPL_SetWriteName"

@{b}   NAME@{ub}
        SPL_SetWriteName  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_SetWriteNameClip(APTR handle, UBYTE *write_name, APTR future)
        D0    -$5a                 A1           A2                 A3

@{b}   FUNCTION@{ub}

        Sets the write_name for a @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"} call.
        See description there and example SourceCodes for more and
        detailed information.

@{b}   INPUT(S)@{ub}

        handle     - a valid handle
        write_name - a valid AmigaDOS FilePath and -Name description
        future     - always NULL yet


@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"}

@EndNode

@Node "SPL_FileInfoRequest()" "superplay.library/SPL_FileInfoRequest"

@{b}   NAME@{ub}
        SPL_FileInfoRequest  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_FileInfoRequest(APTR handle, struct @{"Window" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 797} *window,
        D0    -$60                A1           A2

                                  APTR future)
                                  A3

@{b}   FUNCTION@{ub}

        Pops up an Info-Requester with more or less detailed information
        on the currently loaded Sample/Module.
        A window pointer may be given to select the place to pop it up.

@{b}   INPUT(S)@{ub}

        handle - a valid handle
        window - a valid @{"Window" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 797} Pointer or NULL
        future - always NULL yet


@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_SetReqIOWindow()" Link "SPL_SetReqIOWindow()"}

@EndNode

@Node "SPL_SetReqIOWindow()" "superplay.library/SPL_SetReqIOWindow"

@{b}   NAME@{ub}
        SPL_SetReqIOWindow  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_SetReqIOWindow(APTR handle, struct @{"Window" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 797} *window)
        D0    -$66               A1           A2

@{b}   FUNCTION@{ub}

        Sets a new Default-Window (default : IntuitionBase->FirstWindow)
        for any @{"Requester" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 145} IO.

@{b}   INPUT(S)@{ub}

        handle - a valid handle
        window - a valid @{"Window" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 797} Pointer or NULL

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        SPL_FileInfoReq

@EndNode

@Node "SPL_ReadPlayData()" "superplay.library/SPL_ReadPlayData"

@{b}   NAME@{ub}
        SPL_ReadPlayData  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_ReadPlayData(APTR handle, char *filename)
        D0    -$6c             A1           A2

@{b}   FUNCTION@{ub}

        Loads but NOT plays the data of the Sample/Module described by
        FileName.
        The handle is initialized and the fitting SPObject is opened
        to access the Sample/Module data for use with @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"}.

@{b}   INPUT(S)@{ub}

        handle   - a valid handle
        filename - a valid AmigaDOS FilePath and -Name

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_SetWriteName()" Link "SPL_SetWriteName()"}, @{"SPL_SetWriteType()" Link "SPL_SetWriteType()"}, @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"}

@EndNode

@Node "SPL_ContinueReplay()" "superplay.library/SPL_ContinueReplay"

@{b}   NAME@{ub}
        SPL_ContinueReplay  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_ContinueReplay(APTR handle)
        D0    -$72               A1

@{b}   FUNCTION@{ub}

        Some SPObjects support to continue a Sample/Module which
        has been stopped by calling @{"SPL_StopReplay()" Link "SPL_StopReplay()"}.

@{b}   INPUT(S)@{ub}

        handle - a valid handle

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_SuperPlay()" Link "SPL_SuperPlay()"}, @{"SPL_StopReplay()" Link "SPL_StopReplay()"}

@EndNode

@Node "SPL_FastForward()" "superplay.library/SPL_FastForward"

@{b}   NAME@{ub}
        SPL_FastForward  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_FastForward(APTR handle)
        D0    -$78            A1

@{b}   FUNCTION@{ub}

        Some SPObjects might support a "cassette recorder"-like way
        to browse trough a Sample/Module via FastForward and Rewind.

@{b}   INPUT(S)@{ub}

        handle - a valid handle

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_FastBackward()" Link "SPL_FastBackward()"}

@EndNode

@Node "SPL_FastBackward()" "superplay.library/SPL_FastBackward"

@{b}   NAME@{ub}
        SPL_FastBackward  (V1)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_FastBackward(APTR handle)
        D0    -$7e            A1

@{b}   FUNCTION@{ub}

        Some SPObjects might support a "cassette recorder"-like way
        to browse trough a Sample/Module via FastForward and Rewind.

@{b}   INPUT(S)@{ub}

        handle - a valid handle

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_FastForward()" Link "SPL_FastForward()"}

@EndNode

@Node "SPL_GetSampleList()" "superplay.library/SPL_GetSampleList"

@{b}   NAME@{ub}
        SPL_GetSampleList  (V2)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_GetSampleList(APTR handle, struct SPO_SampleList **list)
        D0    -$84              A1           A2

@{b}   FUNCTION@{ub}

        While/after loading a Sample-File Version 2 SPObjects might create
        a special list of all Samples, which appear in the File.
        This will usually be one one Sample for SampleFiles, but many more
        for ModuleFiles.

        Not all SPObjects, especially not all ModuleType-SPObjects,
        may support this and will return an error value or an empty list.

@{b}   INPUT(S)@{ub}

        handle - a valid handle
        list   - a pointer to a SPO_SampleList pointer

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_SetSampleList()" Link "SPL_SetSampleList()"}

@EndNode

@Node "SPL_SetSampleList()" "superplay.library/SPL_SetSampleList"

@{b}   NAME@{ub}
        SPL_SetSampleList  (V2)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_SetSampleList(APTR handle, struct SPO_SampleList *list)
        D0    -$8a              A1           A2

@{b}   FUNCTION@{ub}

        For saving Sample-Files with Version 2 SPObjects, there may be used
        a special list of all Samples, which should appear in the File.

        This will usually be one one Sample for SampleFiles, but many more
        for ModuleFiles.

        Not all SPObjects, especially not all ModuleType-SPObjects,
        may support this and can return SPERR_ACTION_NOT_SUPPORTED.

@{b}   INPUT(S)@{ub}

        handle - a valid handle
        list   - a pointer to a SPO_SampleList

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_GetSampleList()" Link "SPL_GetSampleList()"}

@EndNode

@Node "SPL_GetFileType()" "superplay.library/SPL_GetFileType"

@{b}   NAME@{ub}
        SPL_GetFileType  (V4)

@{b}   SYNOPSIS@{ub}

        ULONG SPL_GetFileType(APTR handle, char *filename, ULONG *filetype)
        D0    -$90            A1           A2              A3

@{b}   FUNCTION@{ub}

        Finds out superplay-specific FileType-Code
        (redefined with every re-initialization of the Library) or
        SP_FILE_TYPE_UNKNOWN (== NULL == FALSE).

        Use the following call for a simple check :

        handle   = SPL_AllocHandle(N);
        SPerr    = SPL_GetFileType(handle, filename, &filetype);
                   SPL_FreeHandle(handle);

        This handle should NOT be used for any further operations
        on the file (will be opened and checked twice but only
        closed once, etc).
        Initialization operations are allowed nevertheless
        (e.g. @{"SPL_InitHandleAsClip()" Link "SPL_InitHandleAsClip()"} ).

        Note, that this function fills in FILETYPES, not SUBTYPES.
        For e.g. writing you must specify SUBTYPES.

        FILETYPES are only for short identification and do only
        specify the global file type (8SVX, ST).

@{b}   INPUT(S)@{ub}

        handle   - a valid handle
        filename - a valid AmigaDOS FilePath and -Name
        filetype - pointer to ULONG for SP_FILETYPE-Value

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPL_AllocHandle()" Link "SPL_AllocHandle()"}, @{"SPL_FreeHandle()" Link "SPL_FreeHandle()"}

@EndNode

