@database "SuperPlay_Ref_GER"
@master "HardDisk01:dh2/PRG/SP-Lib/Programmers/autodocs/SuperPlay_Ref_GER.doc"

@Node Main "SuperPlay_Ref_GER.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--"

   VERSION
        $VER: SuperPlay_Ref_GER.doc V5.1 (8.8.96)

   COPYRIGHT
         1994-96 by Andreas R. Kleinert. All rights reserved.

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

   GENERAL
              Andreas R. Kleinert,
              Sandstrasse 1,
              D-57072 Siegen,
              Germany.

        EMail:  Fido             Andreas Kleinert 2:2457/350.18
                Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org

          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)

   HISTORY
                            V2     bug-fixed ClipBoard-Support
                                   with the supplied SPObjects (ak)
                            V3     created working combination of
                                   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)

@EndNode

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

   NAME
        SPL_AllocHandle -- Handle reservieren  (V1)

   SYNOPSIS

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

   FUNCTION

        Reserviert einen Handle zum Zugriff auf ein Sample/Module ber
        SPObjects.

   INPUT(S)

        future - derzeit immer NULL

   RESULT

        Ein Zeiger auf einen neu reservierten Handle oder NULL, falls
        die Reservierung fehlschlgt.

   WARNING

        berprfe, ob das Ergebnis NULL oder ungleich NULL ist!

   SEE ALSO

        SPL_FreeResources, SPL_FreeHandle

@EndNode

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

   NAME
        SPL_FreeHandle -- Handle freigeben (V1)

   SYNOPSIS

        VOID SPL_FreeHandle(APTR handle)
        D0   -$24           A1

   FUNCTION

       Beendet das Abspielen und gibt alle Ressourcen sowie den zuvor mit
       SPL_AllocHandle reservierten Handle frei.

   INPUT(S)

        handle - ein gltiger Handle

   RESULT

        -

   SEE ALSO

        SPL_AllocHandle, SPL_StopReplay, SPL_FreeResources

@EndNode

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

   NAME
        SPL_StopReplay -- Beendet Abspielen des Samples/Modules  (V1)

   SYNOPSIS

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

   FUNCTION

        Beendet das Abspielen des mit den Handle angegebenen Sample/Module.
        Einige SPObjects ermglichen es das Sample/Module durch Aufruf
        von SPL_ContinueReplay weiter abspielen zu lassen, nachdem es
        mit SPL_StopReplay gestoppt worden ist.

   INPUT(S)

        handle - ein gltiger Handle

   RESULT

        -

   SEE ALSO

        SPL_ContinueReplay, SPL_FreeResources, SPL_FreeHandle

@EndNode

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

   NAME
        SPL_FreeResources -- Freigabe nicht bentigter Ressourcen  (V1)

   SYNOPSIS

        VOID SPL_FreeResources(APTR handle)
        D0   -$30              A1

   FUNCTION

        Gibt alle Ressourcen - des mit den Handle angegebenen Samples/Modules
        frei - die nicht bentigt werden, um es einfach nur abzuspielen.
        Das Abspielen des Samples/Modules wird weder gestoppt noch
        unterbrochen.

   INPUT(S)

        handle - ein gltiger Handle

   RESULT

        -

   SEE ALSO

        SPL_AllocHandle, SPL_StopReplay, SPL_FreeHandle

@EndNode

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

   NAME
        SPL_SuperPlay -- Ldt und spielt Sample/Module (V1)

   SYNOPSIS

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

   FUNCTION

        Ldt und spielt das mit den Dateinamen spezifizierte Sample/Module
        ab.
        Das Handle wird initialisiert und das passende SPObject geffnet
        und zum Abspielen des Sample/Module verwendet.

        Das Abspielen kann entweder durch vollstndige Freigabe des
        Handles(SPL_FreeHandle()) beendet oder mit SPL_StopReplay
        unterbrochen werden.

   INPUT(S)

        handle   - ein gltiger Handle
        filename - ein gltiger AmigaDOS Dateipfad und -name

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_AllocHandle, SPL_StopReplay, SPL_ContinueReplay,
        SPL_FastForward, SPL_FastBackward, SPL_FreeHandle

@EndNode

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

   NAME
        SPL_SuperWrite -- Sample/Module speichern (V1)

   SYNOPSIS

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

   FUNCTION

        Normalerweise wird ein Sample/Module mit SPL_SuperPlay geladen
        und abgespielt: Abgesehen von SPL_AllocHandle()/SP_FreeHandle() sind
        hierzu sind keine weiteren Funktionsaufrufe zum Lesen und
        Abpielen der Daten ntig.

        Zum Schreiben - also der Konvertierung eines Samples/Modules -
        mssen folgende Funktionsaufrufe ausgefhrt werden:

        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);


        Wichtig: berprfe den "result" Wert NACH JEDEM Funktionsaufruf
                 (siehe Beispiel Quellcodes) !

        Alle mglichen Werte fr dest_type knnen in der SPOBject-List
        der SuperPlayBase gefunden werden.
        Diese Werte VERNDERN sich bei jeder Neuinitialisierung der
        superplay.library, deshalb mu man sie bei jeden ffnen der
        Library erneut auslesen.

        WENN "source_handle" = NULL,
        wird berprft, ob eine SampeList mittels "SPL_SetSampleList()"
        gesetzt worden ist wenn dies der Fall ist wird diese
        SampleList komplett abgespeichert.

        Ein wird empfohlen den alten Weg zur Konvertierung zwischen
        Dateiformaten und den neuen Weg zum Abspeichern einzelner(selbst
        erstellter) SampleLists zu verwenden.

   INPUT(S)

        handle        - ein gltiger Handle          (zum Schreiben)
        source_handle - ein anderer gltiger Handle  (zum Lesen)

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_AllocHandle, SPL_ReadPlayData, SPL_FreeHandle

@EndNode

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

   NAME
        SPL_InitHandleAsDOS -- Initialisiert Handle fr AmigaDOS  (V1)

   SYNOPSIS

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

   FUNCTION

        Initialisiert den Handle fr den Zugriff ber AmigaDOS hierbei
        wird der angegebene Dateiname benutzt.

        Eine andere Mglichkeit besteht darin den Handle fr den
        Clipboard Zugriff zu initialisieren(abhngig vom jeweiligen
        SPObject, z.B. IFF-8SVX).

   INPUT(S)

        handle - ein gltiger Handle
        future - derzeit immer NULL

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_InitHandleAsClip

@EndNode

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

   NAME
        SPL_InitHandleAsClip -- Initialisiert Handle fr ClipBoard  (V1)

   SYNOPSIS

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

   FUNCTION

        Initialisiert einen Handle fr den Zugriff aufs Clipboard, dabei
        wird ein (mglicherweise) angegebener AmigaDOS Datename ignoriert.

        Die beinahe fast immer benutze Mglichkeit besteht in der
        Initialisierung des Handle zum AmigaDOS Zugriff(wird von
        allen SPObjects untersttzt).

   INPUT(S)

        handle - ein gltiger Handle
        future - derzeit immer NULL

   RESULT

        NULL oder ein SPERR-Fehlercode.

   SEE ALSO

        SPL_InitHandleAsDOS

@EndNode

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

   NAME
        SPL_SetWriteType -- Schreibtyp setzen  (V1)

   SYNOPSIS

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

   FUNCTION

        Setzt den Schreibtyp fr einen @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"} Aufruf.
        Siehe dortige Beschreibung und Beispiel Quellcodes fr weitere
        und detailliertere Informationen.

   INPUT(S)

        handle     - ein gltiger Handle
        write_type - ein gltiger - zeitlich begrenzter - write_type Code
                     aus der SPObject List
        future     - derzeit immer NULL

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_SuperWrite

@EndNode

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

   NAME
        SPL_GetErrorString -- Liefert Fehlertext  (V1)

   SYNOPSIS

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

   FUNCTION

        Liefert den Fehlertext fr eine bestimmte Fehlernummer die
        von einer der superplay.library Funktionen zurckgegeben worden
        ist.

   INPUT(S)

        error_code - eine SPERR-Fehlernummer

   RESULT

        Nur-Lese Zeiger auf einen SPERR-Fehlertext

   SEE ALSO

        -

@EndNode

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

   NAME
        SPL_SetWriteName -- Dateinamen fr @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"} setzen  (V1)

   SYNOPSIS

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

   FUNCTION

        Setzt den Dateinamen fr einen @{"SPL_SuperWrite()" Link "SPL_SuperWrite()"} Aufruf.
        Siehe dortige Beschreibung und Beispiel Quellcodes fr weitere
        und detailliertere Informationen.

   INPUT(S)

        handle     - ein gltiger Handle
        write_name - ein gltiger AmigaDOS Dateipfad und -name
        future     - derzeit immer NULL


   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_SuperWrite

@EndNode

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

   NAME
        SPL_FileInfoRequest -- Zeigt Informationen zum Sample/Module  (V1)

   SYNOPSIS

        ULONG SPL_FileInfoRequest(APTR handle, struct Window *window,
        D0    -$60                A1           A2

                                  APTR future)
                                  A3

   FUNCTION

        Gibt ein Infofenster mit mehr oder weniger detaillierten Informationen
        ber das derzeit geladene Sample/Module aus.
        Es ist mglich einen Zeiger auf ein Fenster anzugeben mit dem
        spezifiziert wird wo dieses Infofenster erscheinen soll.

   INPUT(S)

        handle - ein gltiger Handle
        window - ein gltiger Fensterzeiger oder NULL
        future - derzeit immer NULL


   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_SetReqIOWindow

@EndNode

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

   NAME
        SPL_SetReqIOWindow -- Default Fenster fr Dialogfenster setzen  (V1)

   SYNOPSIS

        ULONG SPL_SetReqIOWindow(APTR handle, struct Window *window)
        D0    -$66               A1           A2

   FUNCTION

        Setzt ein Default-Fenster (default: IntuitionBase->FirstWindow)
        fr alle Dialogfenster.

   INPUT(S)

        handle - ein gltiger Handle
        window - ein gltiger Fensterzeiger oder NULL

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_FileInfoReq

@EndNode

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

   NAME
        SPL_ReadPlayData -- Ldt Daten eines Samples/Modules  (V1)

   SYNOPSIS

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

   FUNCTION

        Ldt die Daten eines mittels des Dateinamen spezifizierten
        Samples/Modules aber spielt diese NICHT ab.
        Das Handle wird initialisiert und das entsprechende SPObject
        geffnet, um mit SPL_SuperWrite auf die Sample/Module Daten
        zugreifen zu knnen.

   INPUT(S)

        handle   - ein gltiger Handle
        filename - ein gltiger AmigaDOS Dateipfad und -name

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_SetWriteName, SPL_SetWriteType, SPL_SuperWrite

@EndNode

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

   NAME
        SPL_ContinueReplay -- Abspielen fortsetzen  (V1)

   SYNOPSIS

        ULONG SPL_ContinueReplay(APTR handle)
        D0    -$72               A1

   FUNCTION

        Einige SPObjects bieten die Mglichkeit das durch SPL_StopReplay
        unterbrochene Abspielen des Samples/Modules durch Aufruf
        dieser Funktion fortzufhren.

   INPUT(S)

        handle - ein gltiger Handle

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_SuperPlay, SPL_StopReplay

@EndNode

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

   NAME
        SPL_FastForward -- Schnellvorlauf  (V1)

   SYNOPSIS

        ULONG SPL_FastForward(APTR handle)
        D0    -$78            A1

   FUNCTION

        Einige SPObjects untersttzen die auch von Kassettenrecordern
        bekannte Mglichkeit des Schnellvor- bzw. rcklaufs durch
        ein Sample/Module.

   INPUT(S)

        handle - ein gltiger Handle

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_FastBackward

@EndNode

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

   NAME
        SPL_FastBackward -- Schnellrcklauf  (V1)

   SYNOPSIS

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

   FUNCTION

        Einige SPObjects untersttzen die auch von Kassettenrecordern
        bekannte Mglichkeit des Schnellvor- bzw. rcklaufs durch
        ein Sample/Module.

   INPUT(S)

        handle - ein gltiger Handle

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_FastForward

@EndNode

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

   NAME
        SPL_GetSampleList -- Zugriff auf SampleList  (V2)

   SYNOPSIS

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

   FUNCTION

        Whrend bzw. nachdem Laden einer Sample-Datei erstellen SPObjects
        der Version 2 eventuell eine spezielle Liste aller Samples die in
        dieser Datei enthalten sind.
        Dies wird in der Regel bei einer Sample-Datei ein Sample sein
        und eine ganze Reihe von Samples bei einen Module.

        Nicht alle SPObjects, speziell nicht alle ModuleType-SPObjects,
        untersttzen dies und werden in diesen Fall eine Fehlernummer oder
        eine leere SampleList als Ergebnis liefern.

   INPUT(S)

        handle - ein gltiger Handle
        list   - ein Zeiger auf einen SPO_SampleList Zeiger

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_SetSampleList

@EndNode

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

   NAME
        SPL_SetSampleList -- SampleList setzen  (V2)

   SYNOPSIS

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

   FUNCTION

        Zum Speichern von Sample-Dateien mit SPObjects der Version 2 kann
        eine spezielle Liste aller Samples, die in dieser Datei erscheinen
        sollen, verwendet werden.

        Dies wird in der Regel bei einer Sample-Datei ein Sample sein
        und eine ganze Reihe von Samples bei einen Module.

        Nicht alle SPObjects, speziell nicht alle ModuleType-SPObjects,
        untersttzen dies und knnten stattdessen ein
        SPERR_ACTION_NOT_SUPPORTED als Fehler liefern.

   INPUT(S)

        handle - ein gltiger Handle
        list   - ein Zeiger auf eine SPO_SampleList

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

        SPL_GetSampleList

@EndNode

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

   NAME
        SPL_GetFileType -- Liefert Dateitypen-Code  (V4)

   SYNOPSIS

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

   FUNCTION

        Findet den SuperPlay spezifischen Dateitypen-Code
        (der bei jeder (neuen)-Initialisierung der Library neu definiert
        wird) oder SP_FILE_TYPE_UNKNOWN (== NULL == FALSE).

        Benutzen Sie folgende Funktionsaufrufe fr eine einfache berprfung:

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

        Dieser Handle darf NICHT fr weitere Operationen mit dieser
        Datei benutzt werden(Datei wird einmal geffnet und zweimal
        berprft aber nur einmal geschlossen, usw.)

        Initialisierungs Funktionen wie @{"SPL_InitHandleAsClip()" Link "SPL_InitHandleAsClip()"} sind
        gar nicht erlaubt.

        Wichtig, diese Funktion setzt nur die FILETYPES und nicht
        die SUBTYPES. Zum Schreiben mssen sie z.B. diese SUBTYPES
        spezifizieren.

        FILETYPES sind nur fr eine einfache Idendifikation gedacht
        und geben nur den allgemeinen Typ an(8SVX, ST).

   INPUT(S)

        handle   - ein gltiger Handle
        filename - ein gltiger AmigaDOS Dateipfad- und -name
        filetype - Zeiger auf ULONG fr SP_FILETYPE-Wert

   RESULT

        NULL oder eine SPERR-Fehlernummer.

   SEE ALSO

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

@EndNode

