home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magazyn Amiga Shareware Floppies
/
ma58.dms
/
ma58.adf
/
superplay-lib_DEV
/
Programmers
/
Docs
/
SuperPlay_Ref_ENG.doc
< prev
next >
Wrap
Text File
|
1996-05-27
|
20KB
|
844 lines
$VER: SuperPlay_Ref_ENG.doc V4.5 (21.10.95)
© 1994-95 by Andreas R. Kleinert. All rights reserved.
- Feel free to translate this Doc-File into other languages. -
Andreas R. Kleinert,
Sandstrasse 1,
D-57072 Siegen,
Germany.
EMail: Fido Andreas Kleinert 2:2457/435.10
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)
Request at least : V2+ for bug-fixed ClipBoard-Support
with the supplied SPObjects
V3+ for a working combination of
SVL_SetSampleList() and SuperWrite() calls
V4+ for filetype recognition without loading
Here is a listing of all currently available functions of the
superplay.library in an Autodoc-like style of description :
SPL_AllocHandle ; since Version 1
SPL_FreeHandle
SPL_StopReplay
SPL_FreeResources
SPL_SuperPlay
SPL_SuperWrite
SPL_InitHandleAsDOS
SPL_InitHandleAsClip
SPL_SetWriteType
SPL_GetErrorString
SPL_SetWriteName
SPL_FileInfoRequest
SPL_SetReqIOWindow
SPL_ReadPlayData
SPL_ContinueReplay
SPL_FastForward
SPL_FastBackward
SPL_GetSampleList ; since Version 2
SPL_SetSampleList
; no functions added in Version 3
SPL_GetFileType ; since Version 4
-----------------------------------------------------------------------------
Functions available since Version 1 :
-----------------------------------------------------------------------------
NAME
SPL_AllocHandle
SYNOPSIS
APTR SPL_AllocHandle(APTR future)
D0 -$1e A1
FUNCTION
Allocates a handle for accessing a Sample/Module via SPObjects.
INPUT(S)
future - always NULL yet
RESULT
A pointer to a new allocated Handle or NULL, if allocation failed.
WARNING
Test, if the result was NULL, or not !
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_FreeResources, SPL_FreeHandle
-----------------------------------------------------------------------------
NAME
SPL_FreeHandle
SYNOPSIS
VOID SPL_FreeHandle(APTR handle)
D0 -$24 A1
FUNCTION
Stops playing, frees all Resources and delocates a Handle, which has
been allocated with SPL_AllocHandle before.
INPUT(S)
handle - a valid handle
RESULT
-
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_AllocHandle, SPL_StopReplay, SPL_FreeResources
-----------------------------------------------------------------------------
NAME
SPL_StopReplay
SYNOPSIS
VOID SPL_StopReplay(APTR handle)
D0 -$2a A1
FUNCTION
Stops playing the Sample/Module, indentified by the handle.
Some SPObjects support to continue the Sample/Module with
SPL_ContinueReplay after calling SPL_StopReplay.
INPUT(S)
handle - a valid handle
RESULT
-
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_ContinueReplay, SPL_FreeResources, SPL_FreeHandle
-----------------------------------------------------------------------------
NAME
SPL_FreeResources
SYNOPSIS
VOID SPL_FreeResources(APTR handle)
D0 -$30 A1
FUNCTION
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.
INPUT(S)
handle - a valid handle
RESULT
-
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_AllocHandle, SPL_StopReplay, SPL_FreeHandle
-----------------------------------------------------------------------------
NAME
SPL_SuperPlay
SYNOPSIS
ULONG SPL_SuperPlay(APTR handle, char *filename)
D0 -$36 A1 A2
FUNCTION
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.
INPUT(S)
handle - a valid handle
filename - a valid AmigaDOS FilePath and -Name
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_AllocHandle, SPL_StopReplay, SPL_ContinueReplay,
SPL_FastForward, SPL_FastBackward, SPL_FreeHandle
-----------------------------------------------------------------------------
NAME
SPL_SuperWrite
SYNOPSIS
ULONG SPL_SuperWrite(APTR handle, APTR source_handle)
D0 -$3c A1 A2
FUNCTION
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 !
*** NEW FEATURE : ***
This functions acts different in Versions >= 3 :
1) If "source_handle" is NULL,
it is checked, whether a SampleList has been set via
"SPL_SetSampleList()", and then this SampleList is completely
saved.
ELSE
2) a) If a Version 1 SPObject is the Source, the old behaviour
takes place.
b) If a Version 2 SPObject takes place, the new SampleList
functions are supported (and completely saved).
So, what's new ? Well, if you've any self-created SampleLists,
you now can save them by just setting them via SPL_SetSampleList()
and then calling SPL_SuperWrite() with NULL parameter for the
Source-SPObject handle.
It is suggested to use the old style for converting between
FileFormats and the new style for saving single (self-created)
SampleLists.
INPUT(S)
handle - a valid handle (used for Write Access)
source_handle - an other valid handle (used for Read Access)
(may be NULL for V2+ SPObjects)
RESULT
NULL or an adequate SPERR-Errorcode.
BUGS
Not a bug, but a limitation in V2 :
The new SampleList feature (NULL as parameter) was first
introduced with the V3 release's SPObjects and Library.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_AllocHandle, SPL_ReadPlayData, SPL_FreeHandle
-----------------------------------------------------------------------------
NAME
SPL_InitHandleAsDOS
SYNOPSIS
ULONG SPL_InitHandleAsDOS(APTR handle, APTR future)
D0 -$42 A1 A2
FUNCTION
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).
INPUT(S)
handle - a valid handle
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
BUGS
During V1.1 upto V1.6 this was done automatically ALWAYS.
This was fixed in V2.1
See BUGS under SPL_InitHandleAsClip.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_InitHandleAsClip
-----------------------------------------------------------------------------
NAME
SPL_InitHandleAsClip
SYNOPSIS
ULONG SPL_InitHandleAsClip(APTR handle, APTR future)
D0 -$48 A1 A2
FUNCTION
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).
INPUT(S)
handle - a valid handle
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
BUGS
From 1.1 to 1.6 this function-call was useless, since
superview.library blocked all medias other than
SPO_MEDIUM_DISK for external SPObjects :
For reading calls, this resulted in a "file not found" message
from superplay.library, for writing calls, this resulted in an
empty filename string, which caused the SPObject to reject the
disk access (other accesses were not set correctly).
This was fixed in 2.1, by using the SPO_SetAccessMode() function
with the right parameters now and by using the "future" parameter
of SPO_CheckFileType() - only when using other media than
SPO_MEDIUM_DISK - as a pointer to an additional SPOCheckFileInfo
structure now.
This is 100% compatible, since superplay.library has always set
this value to NULL, so that older SPObjects will simply ignore
this pointer and newer versions will only interpret it, if it's
not NULL.
SINCE
... version 1 of the superplay.library. (request V2+)
SEE ALSO
SPL_InitHandleAsDOS
-----------------------------------------------------------------------------
NAME
SPL_SetWriteType
SYNOPSIS
ULONG SPL_SetWriteType(APTR handle, ULONG write_type, APTR future)
D0 -$4e A1 A2 A3
FUNCTION
Sets the write_type for a SPL_SuperWrite() call.
See description there and example SourceCodes for more and
detailed information.
INPUT(S)
handle - a valid handle
write_type - a valid temporary write_type code form the SPObject List
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_SuperWrite
-----------------------------------------------------------------------------
NAME
SPL_GetErrorString
SYNOPSIS
char * SPL_GetErrorString(ULONG error_code)
D0 -$54 A1
FUNCTION
Returns the Error Message for a specific Error Code, returned
by any function of the superplay.library.
INPUT(S)
error_code - any SPERR Error Code
RESULT
read-only pointer to a SPERR Error String
SINCE
... version 1 of the superplay.library.
SEE ALSO
-
-----------------------------------------------------------------------------
NAME
SPL_SetWriteName
SYNOPSIS
ULONG SPL_SetWriteNameClip(APTR handle, ULONG write_name, APTR future)
D0 -$5a A1 A2 A3
FUNCTION
Sets the write_name for a SPL_SuperWrite() call.
See description there and example SourceCodes for more and
detailed information.
INPUT(S)
handle - a valid handle
write_name - a valid AmigaDOS FilePath and -Name description
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_SuperWrite
-----------------------------------------------------------------------------
NAME
SPL_FileInfoRequest
SYNOPSIS
ULONG SPL_FileInfoRequest(APTR handle, struct Window *window,
D0 -$60 A1 A2
APTR future)
A3
FUNCTION
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.
INPUT(S)
handle - a valid handle
window - a valid Window Pointer or NULL
future - always NULL yet
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_SetReqIOWindow
-----------------------------------------------------------------------------
NAME
SPL_SetReqIOWindow
SYNOPSIS
ULONG SPL_SetReqIOWindow(APTR handle, struct Window *window)
D0 -$66 A1 A2
FUNCTION
Sets a new Default-Window (default : IntuitionBase->FirstWindow)
for any Requester IO.
INPUT(S)
handle - a valid handle
window - a valid Window Pointer or NULL
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_FileInfoReq
-----------------------------------------------------------------------------
NAME
SPL_ReadPlayData
SYNOPSIS
ULONG SPL_ReadPlayData(APTR handle, char *filename)
D0 -$6c A1 A2
FUNCTION
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.
INPUT(S)
handle - a valid handle
filename - a valid AmigaDOS FilePath and -Name
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_SetWriteName, SPL_SetWriteType, SPL_SuperWrite
-----------------------------------------------------------------------------
NAME
SPL_ContinueReplay
SYNOPSIS
ULONG SPL_ContinueReplay(APTR handle)
D0 -$72 A1
FUNCTION
Some SPObjects support to continue a Sample/Module which
has been stopped by calling SPL_StopReplay.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_SuperPlay, SPL_StopReplay
-----------------------------------------------------------------------------
NAME
SPL_FastForward
SYNOPSIS
ULONG SPL_FastForward(APTR handle)
D0 -$78 A1
FUNCTION
Some SPObjects might support a "cassette recorder"-like way
to browse trough a Sample/Module via FastForward and Rewind.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_FastBackward
-----------------------------------------------------------------------------
NAME
SPL_FastBackward
SYNOPSIS
ULONG SPL_FastBackward(APTR handle)
D0 -$7e A1
FUNCTION
Some SPObjects might support a "cassette recorder"-like way
to browse trough a Sample/Module via FastForward and Rewind.
INPUT(S)
handle - a valid handle
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 1 of the superplay.library.
SEE ALSO
SPL_FastForward
-----------------------------------------------------------------------------
Functions added with Version 2 :
-----------------------------------------------------------------------------
NAME
SPL_GetSampleList
SYNOPSIS
ULONG SPL_GetSampleList(APTR handle, struct SPO_SampleList **list)
D0 -$84 A1 A2
FUNCTION
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.
INPUT(S)
handle - a valid handle
list - a pointer to a SPO_SampleList pointer
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 2 of the superplay.library.
SEE ALSO
SPL_SetSampleList
-----------------------------------------------------------------------------
NAME
SPL_SetSampleList
SYNOPSIS
ULONG SPL_SetSampleList(APTR handle, struct SPO_SampleList *list)
D0 -$8a A1 A2
FUNCTION
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.
INPUT(S)
handle - a valid handle
list - a pointer to a SPO_SampleList
RESULT
NULL or an adequate SPERR-Errorcode.
BUGS
Did not work in V2, because SuperWrite() cannot handle
NULL values for "source_handle", which should indicate, that
a SampleList has been set.
SINCE
... version 2 of the superplay.library (request V3+).
SEE ALSO
SPL_GetSampleList
-----------------------------------------------------------------------------
Functions added with Version 4 :
-----------------------------------------------------------------------------
NAME
SPL_GetFileType
SYNOPSIS
ULONG SPL_GetFileType(APTR handle, char *filename, ULONG *filetype)
D0 -$90 A1 A2 A3
FUNCTION
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() ).
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).
INPUT(S)
handle - a valid handle
filename - a valid AmigaDOS FilePath and -Name
filetype - pointer to ULONG for SP_FILETYPE-Value
RESULT
NULL or an adequate SPERR-Errorcode.
SINCE
... version 4 of the superplay.library.
SEE ALSO
SPL_AllocHandle(), SVL_FreeHandle()
-----------------------------------------------------------------------------