home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / datatypes / fp_adpcm / deliplayers / source / deliplayer.i < prev    next >
Text File  |  1995-07-15  |  14KB  |  391 lines
  1. **
  2. **  $Filename: misc/DeliPlayer.i $
  3. **  $Release: 2.0 $
  4. **  $Revision: 2.10$
  5. **  $Date: 05/02/95$
  6. **
  7. **    Definitions and Macros for creating DeliTracker Player&Genie-modules
  8. **
  9. **    (C) Copyright 1991, 1992, 1993, 1994, 1995 Delirium Softdesign
  10. **        All Rights Reserved
  11. **
  12.  
  13.     IFND    DELITRACKER_PLAYER_I
  14. DELITRACKER_PLAYER_I    SET    1
  15.  
  16.     IFND EXEC_PORTS_I
  17.         INCLUDE "exec/ports.i"
  18.     ENDC
  19.  
  20.     IFND EXEC_TYPES_I
  21.         INCLUDE "exec/types.i"
  22.     ENDC
  23.  
  24.     IFND UTILITY_TAGITEM_I
  25.         INCLUDE "utility/tagitem.i"
  26.     ENDC
  27.  
  28. ;----------------------------------------------------------------------------
  29.  
  30. DELIVERSION    EQU    17            ; Current Version of DeliTracker
  31. DELIREVISION    EQU    4            ; Current Revision of DeliTracker
  32.  
  33.  
  34. ;------------------------ Player Function Offsets ---------------------------
  35.  
  36.  STRUCTURE DeliTrackerPlayer,0
  37.  
  38.     STRUCT    dtp_RTS_code,4            ; RTS for security (private !)
  39.     STRUCT    dtp_ID,8            ; Identifier (private !)
  40.     APTR    dtp_TagArray            ; pointer to TagItem array
  41.     LABEL    dtp_SIZE
  42.  
  43. * The TagItem ID's (ti_Tag values) for the player interface follow.
  44.  
  45. DTP_TagBase    EQU    TAG_USER+$4454
  46.  
  47.     ENUM    DTP_TagBase            ; TagBase
  48.  
  49.     EITEM    DTP_InternalPlayer        ; obsolete
  50.     EITEM    DTP_CustomPlayer        ; player is a customplayer
  51.  
  52.     EITEM    DTP_RequestDTVersion        ; minimum DeliTracker version needed
  53.     EITEM    DTP_RequestKickVersion        ; minimum KickStart version needed
  54. DTP_RequestV37    EQU    DTP_RequestKickVersion    ; obsolete
  55.  
  56.     EITEM    DTP_PlayerVersion        ; actual player version & revision
  57.     EITEM    DTP_PlayerName            ; name of this player
  58.     EITEM    DTP_Creator            ; misc string
  59.  
  60.     EITEM    DTP_Check1            ; Check Format before loading
  61.     EITEM    DTP_Check2            ; Check Format after file is loaded
  62.     EITEM    DTP_ExtLoad            ; Load additional files
  63.     EITEM    DTP_Interrupt            ; Interrupt routine
  64.     EITEM    DTP_Stop            ; Clear Patterncounter
  65.     EITEM    DTP_Config            ; Config Player
  66.     EITEM    DTP_UserConfig            ; User-Configroutine
  67.     EITEM    DTP_SubSongRange        ; Get min&max subsong number
  68.  
  69.     EITEM    DTP_InitPlayer            ; Initialisize the Player
  70.     EITEM    DTP_EndPlayer            ; Player clean up
  71.     EITEM    DTP_InitSound            ; Soundinitialisation routine
  72.     EITEM    DTP_EndSound            ; End sound
  73.     EITEM    DTP_StartInt            ; Start interrupt
  74.     EITEM    DTP_StopInt            ; Stop interrupt
  75.  
  76.     EITEM    DTP_Volume            ; Set Volume
  77.     EITEM    DTP_Balance            ; Set Balance
  78.     EITEM    DTP_Faster            ; Incease playspeed
  79.     EITEM    DTP_Slower            ; Decrease playspeed
  80.     EITEM    DTP_NextPatt            ; Jump to next pattern
  81.     EITEM    DTP_PrevPatt            ; Jump to previous pattern
  82.     EITEM    DTP_NextSong            ; Play next subsong
  83.     EITEM    DTP_PrevSong            ; Play previous subsong
  84.  
  85.     ;--- functions in revision 14 (distributed as Release 1.35) ---
  86.  
  87.     EITEM    DTP_SubSongTest            ; Test, if given subsong is vaild
  88.  
  89.     ;--- functions in revision 16 (distributed as Release 2.01) ---
  90.  
  91.     EITEM    DTP_NewSubSongRange        ; enhanced replacement for DTP_SubSongRange
  92.  
  93.     EITEM    DTP_DeliBase            ; the address of a pointer where DT
  94.                         ; stores a pointer to the DeliGlobals
  95.  
  96.     EITEM    DTP_Flags            ; misc Flags (see below)
  97.  
  98.     EITEM    DTP_CheckLen            ; Length of the Check Code
  99.  
  100.     EITEM    DTP_Description            ; misc string
  101.  
  102.     EITEM    DTP_Decrunch            ; pointer to Decrunch Code
  103.     EITEM    DTP_Convert            ; pointer to Converter Code
  104.  
  105.     EITEM    DTP_NotePlayer            ; pointer to a NotePlayer Structure
  106.     EITEM    DTP_NoteStruct            ; the address of a pointer to the
  107.                         ; NoteStruct Structure
  108.     EITEM    DTP_NoteInfo            ; a pointer where DT stores a pointer
  109.                         ; to the current NoteStruct Structure
  110.     EITEM    DTP_NoteSignal            ; pointer to NoteSignal code
  111.  
  112.     EITEM    DTP_Process            ; pointer to process entry code
  113.     EITEM    DTP_Priority            ; priority of the process
  114.     EITEM    DTP_StackSize            ; stack size of the process
  115.     EITEM    DTP_MsgPort            ; a pointer where DT stores a pointer
  116.                         ; to a port to send its messages
  117.  
  118.     EITEM    DTP_Appear            ; open your window, if you can
  119.     EITEM    DTP_Disappear            ; go dormant
  120.  
  121.     EITEM    DTP_ModuleName            ; get the name of the current module
  122.     EITEM    DTP_FormatName            ; get the name of the module format
  123.     EITEM    DTP_AuthorName            ; not implemented yet
  124.  
  125.     ;--- functions in revision 17 (distributed as Release 2.07) ---
  126.  
  127.     EITEM    DTP_InitNote            ; NoteStruct initialization
  128.  
  129.     EITEM    DTP_PlayTime            ; not implemented yet
  130.  
  131. *** end of player interface enumeration ***
  132.  
  133.  
  134. ; --- various flags ---------------------------------------------------------
  135.  
  136.     BITDEF    PLY,CUSTOM,0            ; the player is a customplayer
  137.     BITDEF    PLY,SONGEND,1            ; this player supports songend
  138.  
  139.     ;--- flags defined in revision 17 (distributed as Release 2.07) ---
  140.  
  141.     BITDEF    PLY,ANYMEM,2            ; modules of this player don't require chipmem
  142.  
  143.  
  144. ; --- DeliTracker message ---------------------------------------------------
  145.  
  146.    STRUCTURE DeliMessage,MN_SIZE
  147.     ULONG    DTMN_Function            ; function pointer
  148.     ULONG    DTMN_Result            ; store the result here
  149.    LABEL DTMN_SIZE
  150.  
  151.  
  152. ;------------------------------ Player Header -------------------------------
  153. ;
  154. ; Here is the MACRO for creating the player header structure. Use this MACRO !!!
  155.  
  156. PLAYERHEADER    MACRO
  157.     IFC    '\2',''
  158.     moveq    #-1,d0            ; this should return an error
  159.     rts                ; in case someone tried to run it
  160.     ELSE
  161.     bra.w    \2            ; branch to startupcode
  162.     ENDC
  163.     dc.b    'DELIRIUM'        ; identifier
  164.     dc.l    \1            ; ^tagitem array
  165.     ENDM
  166.  
  167.  
  168.     ;------ When a subroutine in the player is called, A5 will contain
  169.     ;------ the pointer to the DeliTrackerGlobals, the only exeption is
  170.     ;------ of course the interrupt routine.
  171.     ;------ The interruptroutine is called every 1/50 sec (via timerint).
  172.  
  173.     ;------ When Check is called, supply d0=0 if the format is ok
  174.     ;------ else d0<>0.
  175.  
  176.     ;------ Check1 is called before loading the complete file, you can
  177.     ;------ check in the first 1024 Bytes of the file. If the file is
  178.     ;------ smaller than 1kB, the remaining space will contain zero.
  179.  
  180.     ;------ Check2 is called after the complete file is loaded, you
  181.     ;------ can use dtg_ChkSize to determine the length of the file.
  182.     ;------ If you supply this tag the file can be crunched.
  183.  
  184.     ;------ ExtLoad: routine for loading additional files (instruments).
  185.     ;------    If successful, you must return d0=0 else d0<>0. In case of
  186.     ;------ an error DeliTracker frees all memory used for this module.
  187.  
  188.     ;------    InitPlayer: Here you should allocate the audio channels.
  189.     ;------ In case the player supports multi-modules, you must set here
  190.     ;------ dtg_SndNum to the minimal subsong number (not necessary if
  191.     ;------ you have supplied a DTP_SubSongRange routine!).
  192.     ;------ If successful, you must return d0=0 else d0<>0.
  193.  
  194.     ;------    EndPlayer: Here you should free the audio channels.
  195.  
  196.     ;------ InitSound: If you want to use the internal interrupt but don't
  197.     ;------ need the default 50 Hz frequency, you can write another timer
  198.     ;------ value into dtg_Timer.
  199.  
  200.     ;------ It is recommended to use DTP_SubSongRange/DTP_SubSongTest
  201.     ;------ instead of DTP_NextSong/DTP_PrevSong.
  202.  
  203.     ;------ Volume usually only copies the values dtg_Volume, dtg_SndLBal
  204.     ;------ and dtg_SndRBal to an internal buffer. The interrupt code has
  205.     ;------ access to this buffer and can set the volume correct.
  206.  
  207.     ;------ CheckLen: This tag is only allowed for players. If you supply
  208.     ;------ this tag, the player will be unloaded by DeliTracker in low
  209.     ;------ memory situations. When needed, it will be loaded again
  210.     ;------ automatically.
  211.  
  212.     ;------ Decrunch: Supply d0=0 if you could decrunch the file else
  213.     ;------ d0<>0.
  214.  
  215.     ;------ Convert: Supply d0=0 if you converted the file to another
  216.     ;------ format, else d0<>0.
  217.  
  218.     ;------ Appear: Supply d0<>0 if the window was already opend, else
  219.     ;------ d0=0.
  220.  
  221.     ;------ Disappear: Supply d0=0 if the window was already closed, else
  222.     ;------ d0<>0.
  223.  
  224.     ;------ ModuleName: This tag is only allowed for players. It contains
  225.     ;------ the address of a pointer to the module name (must be null
  226.     ;------ terminated). The tag is evaluated after the InitPlayer function
  227.     ;------ was called.
  228.  
  229.     ;------ FormatName: This tag is only allowed for convert genies. It
  230.     ;------ contains the address of a pointer to the name of the module
  231.     ;------ format (must be null terminated). The tag is evaluated after
  232.     ;------ the InitPlayer function was called.
  233.  
  234.     ;------ AuthorName: This tag is only allowed for players. It contains
  235.     ;------ the address of a pointer to the authorname (must be null
  236.     ;------ terminated). The tag is evaluated after the InitPlayer function
  237.     ;------ was called.
  238.  
  239.     ;------ Note: the Player can consist of more Hunks. That means you
  240.     ;------ can seperate CHIP DATA form CODE (and you should do this!).
  241.  
  242.  
  243. ;---------------------------- Global Variables ------------------------------
  244.  
  245.  STRUCTURE DeliTrackerGlobals,0
  246.  
  247.     ;------ if you use dtg_AslBase, make sure that
  248.     ;------ DTP_RequestDTVersion is at least 13 !
  249.  
  250.     APTR    dtg_AslBase        ; librarybase don't CloseLibrary()
  251.  
  252.     APTR    dtg_DOSBase        ; librarybase -"-
  253.     APTR    dtg_IntuitionBase    ; librarybase -"-
  254.     APTR    dtg_GfxBase        ; librarybase -"-
  255.     APTR    dtg_GadToolsBase    : librarybase -"- (NULL for Kick 1.3 and below)
  256.     APTR    dtg_ReservedLibraryBase    ; reserved for future use
  257.  
  258.     APTR    dtg_DirArrayPtr        ; Ptr to the directory of the current module
  259.     APTR    dtg_FileArrayPtr    ; Ptr to the filename of the current module
  260.     APTR    dtg_PathArrayPtr    ; Ptr to PathArray (e.g used in LoadFile())
  261.  
  262.     APTR    dtg_ChkData        ; pointer to the module to be checked
  263.     ULONG    dtg_ChkSize        ; size of the module
  264.  
  265.     UWORD    dtg_SndNum        ; current sound number
  266.     UWORD    dtg_SndVol        ; volume (ranging from 0 to 64)
  267.     UWORD    dtg_SndLBal        ; left volume (ranging from 0 to 64)
  268.     UWORD    dtg_SndRBal        ; right volume (ranging from 0 to 64)
  269.     UWORD    dtg_LED            ; filter (0 if the LED is off)
  270.     UWORD    dtg_Timer        ; timer-value for the CIA-Timers
  271.  
  272.     FPTR    dtg_GetListData        ;
  273.     FPTR    dtg_LoadFile        ;
  274.     FPTR    dtg_CopyDir        ;
  275.     FPTR    dtg_CopyFile        ;
  276.     FPTR    dtg_CopyString        ;
  277.     FPTR    dtg_AudioAlloc        ;
  278.     FPTR    dtg_AudioFree        ;
  279.     FPTR    dtg_StartInt        ;
  280.     FPTR    dtg_StopInt        ;
  281.     FPTR    dtg_SongEnd        ; save to call from interrupt code !
  282.     FPTR    dtg_CutSuffix        ;
  283.  
  284.     ;------ extension in revision 14
  285.  
  286.     FPTR    dtg_SetTimer        ; save to call from interrupt code !
  287.  
  288.     ;------ extension in revision 15
  289.  
  290.     FPTR    dtg_WaitAudioDMA    ; save to call from interrupt code !
  291.  
  292.     ;------ extension in revision 16
  293.  
  294.     FPTR    dtg_LockScreen
  295.     FPTR    dtg_UnlockScreen
  296.     FPTR    dtg_NotePlayer        ; save to call from interrupt code !
  297.     FPTR    dtg_AllocListData
  298.     FPTR    dtg_FreeListData
  299.  
  300.     FPTR    dtg_Reserved1        ; do not use !!!
  301.     FPTR    dtg_Reserved2        ; do not use !!!
  302.     FPTR    dtg_Reserved3        ; do not use !!!
  303.  
  304.     ; There is no dtg_SIZEOF cause ...
  305.  
  306.  
  307.     ;------ GetListData(Num:d0): This function returns the memorylocation
  308.     ;------ of a loaded file in a0 and its size in d0. Num starts with 0
  309.     ;------ (the selected module). Example: GetListData(2) returns the
  310.     ;------ start of the third file loaded (via ExtLoad) in a0 an its size
  311.     ;------ in d0.
  312.  
  313.     ;------ LoadFile(): this function may only be called in the ExtLoad
  314.     ;------ routine. file/pathname must be in dtg_PathArrayPtr then
  315.     ;------ this function will attempt to load the file into CHIPMEM
  316.     ;------ (and DECRUNCH it). If everything went fine, d0 will be zero.
  317.     ;------ If d0 is not zero this indicates an error (e.g. read error,
  318.     ;------ not enough memory, ...).
  319.  
  320.     ;------ CopyDir(): this function copies the pathname at the end
  321.     ;------ of the string in dtg_PathArrayPtr(a5).
  322.  
  323.     ;------ CopyFile(): this function copies the filename at the end
  324.     ;------ of the string in dtg_PathArrayPtr(a5).
  325.  
  326.     ;------ CopyString(Ptr:a0): this function copies the string in a0
  327.     ;------ at the end of the string in dtg_PathArrayPtr(a5).
  328.  
  329.     ;------ AudioAlloc(): this function allocates the audiochannels
  330.     ;------ (only necessary if the player doesn't supply a NoteStruct
  331.     ;------ tag). If d0=0 all is ok, d0<>0 indicates an error.
  332.  
  333.     ;------ AudioFree(): this function frees the audiochannels allocated
  334.     ;------ with AudioAlloc().
  335.  
  336.     ;------ StartInt(): this function starts the timer-interrupt.
  337.  
  338.     ;------ StopInt(): this function stops the timer-interrupt started
  339.     ;------ with StartInt().
  340.  
  341.     ;------ SongEnd(): signal the songend to DeliTracker.
  342.     ;------ This call is guaranteed to preserve all registers.
  343.  
  344.     ;------ CutSuffix(): this function removes the suffix '.xpk' or '.pp'
  345.     ;------ from the string in dtg_PathArrayPtr(a5).
  346.  
  347.     ;------ SetTimer(): programs the CIA-Timer with the value supplied
  348.     ;------ in dtg_Timer(a5). Only useful, if the internal timer-interrupt
  349.     ;------ is used. This call is guaranteed to preserve all registers.
  350.  
  351.     ;------ WaitAudioDMA(): DMA delay wait. Only allowed, if the internal
  352.     ;------ timer-interrupt is used. This call is guaranteed to preserve
  353.     ;------ all registers.
  354.  
  355.     ;------ LockScreen(): this function tries to lock DeliTracker's screen.
  356.     ;------ It returns the screenpointer in d0 or NULL on failure.
  357.  
  358.     ;------ UnlockScreen(): this function unlocks DeliTracker's screen.
  359.     ;------ do not unlock a screen more times than it was locked!
  360.  
  361.     ;------ NotePlayer(): this call plays the notes specified in the
  362.     ;------ current NoteStruct structure. This function call is not allowed
  363.     ;------ if the active player doesn't have a valid NotePlayer structure.
  364.     ;------ do not call this function in interrupt code at interrupt
  365.     ;------ level 5 or higher! This call is guaranteed to preserve
  366.     ;------ all registers.
  367.  
  368.     ;------ AllocListData(Size:d0/Flags:d1): This is the memory allocator
  369.     ;------ for module specific memory to be used by all players and genies.
  370.     ;------ It provides a means of specifying that the allocation should be
  371.     ;------ made in a memory area accessible to the chips, or accessible to
  372.     ;------ shared system memory. If the allocation is successful,
  373.     ;------ DeliTracker will keep track of the new block (GetListData() will
  374.     ;------ return the location and size of this block).
  375.     ;------ byteSize - the size of the desired block in bytes.
  376.     ;------ Flags - the flags are passed through to AllocMem().
  377.     ;------ A pointer to the newly allocated memory block is returned in d0.
  378.     ;------ If there are no free memory regions large enough to satisfy the
  379.     ;------ request, zero will be returned. The pointer must be checked
  380.     ;------ for zero before the memory block may be used!
  381.  
  382.     ;------ FreeListData(MemBlock:a1): Free a region of memory allocated
  383.     ;------ with AllocListData(), returning it to the system pool from which
  384.     ;------ it came.
  385.     ;------ memoryBlock - pointer to the memory block to free, or NULL.
  386.  
  387.  
  388.     ENDC    ; DELITRACKER_PLAYER_I
  389.  
  390.  
  391.