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

@Node Main "SPObject_Ref_ENG.doc"
    @{" --background-- " Link "--background--"}
    @{" SPO_AllocHandle() " Link "SPO_AllocHandle()"}
    @{" SPO_FreeHandle() " Link "SPO_FreeHandle()"}
    @{" SPO_Read() " Link "SPO_Read()"}
    @{" SPO_StartReplay() " Link "SPO_StartReplay()"}
    @{" SPO_Write() " Link "SPO_Write()"}
    @{" SPO_StopReplay() " Link "SPO_StopReplay()"}
    @{" SPO_FreeResources() " Link "SPO_FreeResources()"}
    @{" SPO_SetAccessMode() " Link "SPO_SetAccessMode()"}
    @{" SPO_SetWriteSubType() " Link "SPO_SetWriteSubType()"}
    @{" SPO_SetWriteName() " Link "SPO_SetWriteName()"}
    @{" SPO_SetReadName() " Link "SPO_SetReadName()"}
    @{" SPO_FileInfoRequest() " Link "SPO_FileInfoRequest()"}
    @{" SPO_CheckFileType() " Link "SPO_CheckFileType()"}
    @{" SPO_SetReqIOWindow() " Link "SPO_SetReqIOWindow()"}
    @{" SPO_ContinueReplay() " Link "SPO_ContinueReplay()"}
    @{" SPO_FastForward() " Link "SPO_FastForward()"}
    @{" SPO_FastBackward() " Link "SPO_FastBackward()"}
    @{" SPO_GetSampleBuffer() " Link "SPO_GetSampleBuffer()"}
    @{" SPO_GetSampleInfo() " Link "SPO_GetSampleInfo()"}
    @{" SPO_GetSampleList() " Link "SPO_GetSampleList()"}
    @{" SPO_SetSampleList() " Link "SPO_SetSampleList()"}
@EndNode

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

@{b}   VERSION@{ub}
        $VER: SPObject_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}   NOTE@{ub}
        * DO _NEVER_ ACCESS ANY SPOBJECTS DIRECTLY.
        * DO NEVER BYPASS superplay.library !

        THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SPOBJECTS :


@{b}   HISTORY@{ub}
        V2.5   Autodoc format
               Change one SVO_ prefix to SPO_
               Add version behind NAME
               SPObject.library/SPO_SetReadeName
                                         ^
                 -> SPObject.library/SPO_SetReadName(indy)
        V5.1   applied some more changes (ak)
        V5.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 "SPO_AllocHandle()" "SPObject.library/SPO_AllocHandle"

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

@{b}   SYNOPSIS@{ub}

        APTR SPO_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}

        @{"SPO_FreeResources()" Link "SPO_FreeResources()"}, @{"SPO_FreeHandle()" Link "SPO_FreeHandle()"}

@EndNode

@Node "SPO_FreeHandle()" "SPObject.library/SPO_FreeHandle"

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

@{b}   SYNOPSIS@{ub}

        VOID SPO_FreeHandle(APTR handle)
        D0   -$24           A1

@{b}   FUNCTION@{ub}

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

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

        handle - a valid handle

@{b}   RESULT@{ub}

        -

@{b}   SEE ALSO@{ub}

        @{"SPO_AllocHandle()" Link "SPO_AllocHandle()"}, @{"SPO_StopReplay()" Link "SPO_StopReplay()"}, @{"SPO_FreeResources()" Link "SPO_FreeResources()"}

@EndNode

@Node "SPO_Read()" "SPObject.library/SPO_Read"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_Read(APTR handle)
        D0    -$2a     A1

@{b}   FUNCTION@{ub}

        Loads the Sample/Module described by FileName, which then may
        e.g. be replayed by @{"SPO_StartReplay()" Link "SPO_StartReplay()"}.

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

        handle   - a valid handle

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPO_AllocHandle()" Link "SPO_AllocHandle()"}, @{"SPO_StopReplay()" Link "SPO_StopReplay()"}, @{"SPO_StartReplay()" Link "SPO_StartReplay()"},
        @{"SPO_ContinueReplay()" Link "SPO_ContinueReplay()"}, @{"SPO_FastForward()" Link "SPO_FastForward()"}, @{"SPO_FastBackward()" Link "SPO_FastBackward()"},
        @{"SPO_FreeHandle()" Link "SPO_FreeHandle()"}

@EndNode

@Node "SPO_StartReplay()" "SPObject.library/SPO_StartReplay"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_StartReplay(APTR handle)
        D0    -$30            A1

@{b}   FUNCTION@{ub}

        Play the Sample/Module described by FileName, which has been loaded
        via @{"SPO_Read()" Link "SPO_Read()"} before.

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

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

        handle   - a valid handle

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPO_AllocHandle()" Link "SPO_AllocHandle()"}, @{"SPO_Read()" Link "SPO_Read()"}, @{"SPO_StopReplay()" Link "SPO_StopReplay()"},
        @{"SPO_ContinueReplay()" Link "SPO_ContinueReplay()"}, @{"SPO_FastForward()" Link "SPO_FastForward()"}, @{"SPO_FastBackward()" Link "SPO_FastBackward()"},
        @{"SPO_FreeHandle()" Link "SPO_FreeHandle()"}

@EndNode

@Node "SPO_Write()" "SPObject.library/SPO_Write"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_Write(APTR handle, struct SPObjectBase *SourceBase,
        D0    -$36      A1           A2

                        APTR source_handle)
                        A3

@{b}   FUNCTION@{ub}

        This functions allows to access an other SPObject, get the Sample-
        Data from there (only works with SampleType-SPObjects) and
        then writes this data in its own FileFormat.

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

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

        handle        - a valid handle
                        (used for Write Access)
        SourceBase    - pointer to Base of other SPObject
                        (may be NULL for V2+ SPObjects)
        source_handle - handle for accessing the other SPObject
                        (may be NULL for V2+ SPObjects)

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPO_AllocHandle()" Link "SPO_AllocHandle()"}, @{"SPO_Read()" Link "SPO_Read()"}, @{"SPO_FreeHandle()" Link "SPO_FreeHandle()"}

@EndNode

@Node "SPO_StopReplay()" "SPObject.library/SPO_StopReplay"

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

@{b}   SYNOPSIS@{ub}

        VOID SPO_StopReplay(APTR handle)
        D0   -$3c           A1

@{b}   FUNCTION@{ub}

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

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

        handle - a valid handle

@{b}   RESULT@{ub}

        -

@{b}   SEE ALSO@{ub}

        @{"SPO_ContinueReplay()" Link "SPO_ContinueReplay()"}, @{"SPO_FreeResources()" Link "SPO_FreeResources()"}, @{"SPO_FreeHandle()" Link "SPO_FreeHandle()"}

@EndNode

@Node "SPO_FreeResources()" "SPObject.library/SPO_FreeResources"

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

@{b}   SYNOPSIS@{ub}

        VOID SPO_FreeResources(APTR handle)
        D0   -$42              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}

        @{"SPO_AllocHandle()" Link "SPO_AllocHandle()"}, @{"SPO_StopReplay()" Link "SPO_StopReplay()"}, @{"SPO_FreeHandle()" Link "SPO_FreeHandle()"}

@EndNode

@Node "SPO_SetAccessMode()" "SPObject.library/SPO_SetAccessMode"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_SetAccessMode(APTR handle, ULONG mode)
        D0    -$48              A1           D1

@{b}   FUNCTION@{ub}

        Initializes a Handle for ClipBoard or AmigaDOS access,
        depending on the "mode" parameter.

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

        handle - a valid handle
        mode   - access mode value


@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        -

@EndNode

@Node "SPO_SetWriteSubType()" "SPObject.library/SPO_SetWriteSubType"

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

@{b}   SYNOPSIS@{ub}

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

@{b}   FUNCTION@{ub}

        Sets the write_type for a @{"SPO_Write()" Link "SPO_Write()"} 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}

        @{"SPO_Write()" Link "SPO_Write()"}

@EndNode

@Node "SPO_SetWriteName()" "SPObject.library/SPO_SetWriteName"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_SetWriteName(APTR handle, UBYTE *write_name, APTR future)
        D0    -$54             A1           A2                 A3

@{b}   FUNCTION@{ub}

        Sets the write_name for a @{"SPO_Write()" Link "SPO_Write()"} 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}

        @{"SPO_Write()" Link "SPO_Write()"}

@EndNode

@Node "SPO_SetReadName()" "SPObject.library/SPO_SetReadName"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_SetReadName(APTR handle, ULONG reade_name, APTR future)
        D0    -$5a            A1           A2                A3

@{b}   FUNCTION@{ub}

        Sets the reade_name for a @{"SPO_Read()" Link "SPO_Read()"} 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}

        @{"SPO_Write()" Link "SPO_Write()"}

@EndNode

@Node "SPO_FileInfoRequest()" "SPObject.library/SPO_FileInfoRequest"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_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}

        @{"SPO_SetReqIOWindow()" Link "SPO_SetReqIOWindow()"}

@EndNode

@Node "SPO_CheckFileType()" "SPObject.library/SPO_CheckFileType"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_CheckFileType(BPTR filehandle, UBYTE *filename,
        D0    -$66              A1                 A2

                                struct SPOCheckFile *spo_check)
                                A3

@{b}   FUNCTION@{ub}

        Checks, if the given file (or ClipBoard entry, or whatever)
        fits to this SPObject and can be handled therein.

        Other media as SPO_MEDIUM_DISK requite spo_check to
        be non-NULL and initialized.

        Be prepared, to handle NULL pointers to filename and handle.

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

        handle    - a valid handle
        name      - a valid AmigaDOS FileName
        spo_check - a pointer to a SPOCheckFile structure or NULL
                    for disk-access (default)

@{b}   RESULT@{ub}

        NULL or an adequate SVERR-Errorcode.

@{b}   SEE ALSO@{ub}

        -

@EndNode

@Node "SPO_SetReqIOWindow()" "SPObject.library/SPO_SetReqIOWindow"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_SetReqIOWindow(APTR handle, struct @{"Window" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 797} *window)
        D0    -$6c               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}

        SPO_FileInfoReq

@EndNode

@Node "SPO_ContinueReplay()" "SPObject.library/SPO_ContinueReplay"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_ContinueReplay(APTR handle)
        D0    -$72               A1

@{b}   FUNCTION@{ub}

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

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

        handle - a valid handle

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        SPO_SuperPlay(), @{"SPO_StopReplay()" Link "SPO_StopReplay()"}

@EndNode

@Node "SPO_FastForward()" "SPObject.library/SPO_FastForward"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_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}

        @{"SPO_FastBackward()" Link "SPO_FastBackward()"}

@EndNode

@Node "SPO_FastBackward()" "SPObject.library/SPO_FastBackward"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_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}

        @{"SPO_FastForward()" Link "SPO_FastForward()"}

@EndNode

@Node "SPO_GetSampleBuffer()" "SPObject.library/SPO_GetSampleBuffer"

@{b}   NAME@{ub}
        SPO_GetSampleBuffer  (V1)   *** OBSOLETE : Use @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"}

@{b}   SYNOPSIS@{ub}

        ULONG SPO_GetSampleBuffer(APTR handle, UBYTE **buffer,
        D0    -$84                A1           A2

                                  ULONG *buffersize)
                                  A3

@{b}   FUNCTION@{ub}

        This function is OBSOLETE. Don't use it.

        Use @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"} instead, which can handle more than one
        Sample and also returns the information related to them.

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

        handle     - a valid handle
        buffer     - a pointer to a buffer pointer
        buffersize - a pointer to a buffersize pointer

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"}

@EndNode

@Node "SPO_GetSampleInfo()" "SPObject.library/SPO_GetSampleInfo"

@{b}   NAME@{ub}
        SPO_GetSampleInfo  (V1)     *** OBSOLETE : Use @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"}

@{b}   SYNOPSIS@{ub}

        ULONG SPO_GetSampleInfo(APTR handle, ULONG *samplesPerSec,
        D0    -$8a              A1           A2

                                ULONG *volume, APTR future)
                                A3             D1

@{b}   FUNCTION@{ub}

        This function is OBSOLETE. Don't use it.

        Use @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"} instead, which can handle more than one
        Sample and also returns the information related to them.

        This function only returns info on 8 Bit Samples.

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

        handle        - a valid handle
        samplesPerSec - a pointer to a buffer pointer
        volume        - a pointer to a buffersize pointer
        future        - always NULL yet

@{b}   RESULT@{ub}

        NULL or an adequate SPERR-Errorcode.

@{b}   SEE ALSO@{ub}

        @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"}

@EndNode

@Node "SPO_GetSampleList()" "SPObject.library/SPO_GetSampleList"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_GetSampleList(APTR handle, struct SPO_SampleList **list)
        D0    -$90              A1           A2

@{b}   FUNCTION@{ub}

        While/after loading a Sample-File 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}

        @{"SPO_SetSampleList()" Link "SPO_SetSampleList()"}

@EndNode

@Node "SPO_SetSampleList()" "SPObject.library/SPO_SetSampleList"

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

@{b}   SYNOPSIS@{ub}

        ULONG SPO_SetSampleList(APTR handle, struct SPO_SampleList *list)
        D0    -$96              A1           A2

@{b}   FUNCTION@{ub}

        For saving Sample-Files with, 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 will 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}

        @{"SPO_GetSampleList()" Link "SPO_GetSampleList()"}

@EndNode

