

                  DCDUtils v0.15,  Andr Timmermans 1998


Introduction


  DCDUtils is a helper for DigitalCD sound visualization plug-ins, but may
  also be used by any other player that follows the protocol.


The player's protocol


  The player's register itself to the module by calling the SWI 
  DCDUtils_RegisterPlayer which will return you an handle for the player
  that you will have to use in every call made to the module.

  Next, you will provide the module with some information about the player,
  and keep that information up to date. This is done by calling the SWI
  DCDUtils_SetPlayerInfo just after DCDUtils_RegisterPlayer.

  How plug-ins are started is totally irrelevant to the module but I suggest
  you stick to the method described in !DigitalCD.Docs.PlugIns if you which
  to be able to reuse them.

  From now on you only have keep plug-ins informed of changes in your player:
  - call DCDUtils_SetPlayerInfo for a new song, a new volume level, etc.
  - call DCDUtils_UpdatePlugInsPosition when the player's window is moved.

  Finally, on exit you just call DCDUtils_UnregisterPlayer (which will also
  stop the plug-ins for you).
  
  Additional programming notes:

    You should call DCDUtils_StopPlugIns when the player's window is closed,
    otherwise plug-ins could remain on screen.

    DCDUtils_GetFullScreenPlugIn is available for detecting the presence
    of a full screen plug-in. This may be useful as such plug-ins will forward
    you any keypress they do not handle themselves, and I advise to check in
    the presence of a full screen plug-in to intercept special keys such as F12
    and do not attempt to open dialog boxes.


The plug-in's protocol

  
+ The plug-in register itself to the module by calling the SWI
  DCDUtils_RegisterPlugIn which will return you an handle that you will have
  to use in every call made to the module. You will have to state the player's
  handle to visualise (DigitalCD will give it as parameter when running the
  plug-in) , your task handle (so Wimp_Initialise needs to be called first)
  and if the plug-in is full screen.

  Stating a full screen plug-in is useful as the module will then save the
  current screen mode and restore it when you unregister the plug-in.
  In addition it will try to prevent the activation of screen savers while your
  plug-in is working (works only for the ScreenBlanker and Delirium 2.22 at
  the moment).

+ To get information on the player call DCDUtils_GetPlayerInfo, but do it
  each time you require information and not once and for all at the beginning
  of the program as every bit of information provide is subject to change
  with the time even the player's window handle (because of skins or mini-bars
  in the case of DigitalCD).

+ As the main purpose is visualisation, you will certainly make in your
  Wimp_PollIdle null events call to either DCDUtils_FillBuffer or
  DCDUtils_FillRawBuffer to fill a short wave buffer representing the player's
  output. The only difference between the two calls is that in the first case
  the buffer is rescaled according to the player's volume so that the
  visualisation can be volume independent, while in the second case you get
  the real buffer.

+ If your plug-in is to attach itself to the borders of the player's window,
  monitoring the windows position on NULL events will give bad results as you
  will to receive such events before the user has finished the dragging.
  Instead monitor the message Message_UpdatePlugInsPosition (&52780) which
  the player will sent each time it's window is moved.

+ On exit from the plug-in, call DCDUtils_UnregisterPlugIn.
  
  
  Finally, comes a list of rules to follow by plug-ins:

  - It must multitask by calling Wimp_Poll periodically.
  - It must exit cleanly on receipt of the Message_Quit (0) message.
  - The plug-in may change screen mode using the BASIC 'MODE' command, or
    OS_ScreenMode. Do not use Wimp_SetMode or you'll screw up the desktop,
    and don't change the screen mode if you didn't register the plug-in as
    a full screen plug-in first, otherwise DCDUtils will not be able to save
    and restore the desktop state.
  - Whatever occurs, you should exit from your code properly, not forgetting
    to unregister the plug-in, so don't forget to set up error handlers
    to trap errors occurring on the code. What you decide to do when the error
    occurs is irrelevant: you may exit from the code or continue, silence the
    error, log it in a file or even report it (thought not recommended for
    full-screen plug-ins). To trap the errors, in BASIC you could use ON ERROR,
    and in C use signal handlers and some exception handling library.


Contacts


  You can contact me using email at:

    Andre.Timmermans@sbs.be

  or using smail address:

    Timmermans Andr
    Rue du Vert Coron, 17
    7600 Pruwelz
    Belgium



                                 SWI Interface

   
  Warning: on SWI exit flags are corrupted


DCDUtils_Version &52780


    Returns the current version of the module.

  On entry

    -

  On exit

    R0 = version * 100


DCDUtils_RegisterPlayer &52781


    Reserved to players (DigitalCD), register a player to the module.

  On entry

    R0 = 0 (Reserved)

  On exit

    R0 = player handle


DCDUtils_UnregisterPlayer &52782


    Reserved to players, unregister a player to the module.

  On entry

    R0 = player handle

  On exit

    -


DCDUtils_RegisterPlugIn &52783


    Reserved for plug-ins, register a plug-in to the module.

  On entry

    R1 = player handle
    R2 = plug-in task handle
    R3 = flags
          0x00000001 full screen plug-in

  On exit

    R0 = plug-in handle


DCDUtils_UnregisterPlugIn &52784


    Reserved for plug-ins, unregister a plug-in to the module.

  On entry

    R0 = plug-in handle

  On exit

    -


DCDUtils_SetPlayerInfo &52785


    Reserved to players, feeds the module with info from a player.

  On entry
  
    R0 = player handle
    R1 = control panel window handle
    R2 = songs counter
    R3 = song volume [0, 256]
    R4 = song name pointer (null terminated)
    R5 = input source
          0     audio DMA
          1,... reserved for new hardware with line-in, cd-in, ... ?

  On exit
  
    -

  Use

    Reserved to DigitalCD, for details see next SWI.


DCDUtils_GetPlayerInfo &52786


    Reserved for plug-ins, returns info about a player.

  On entry
  
    R0 = player handle

  On exit
  
    R1 = control panel window handle
    R2 = songs counter
    R3 = song volume [0, 256]
    R4 = song name pointer (null terminated)
    R5 = input source
          0     audio DMA
          1,... reserved for new hardware with line-in, cd-in, ... ?

  Use

    This SWI should be called each time the plug-in requires information
    from DigitalCD as this information may vary in time.

    The control panel window handle will change every time the user switch
    between mini/full control panel and at each skin change. It has two
    main usages:

    - windowed plug-in: dock plug-in windows near borders of the control panel.
    - full screen plug-in: pass unprocessed keypresses back to the the control
      panel so that shortcuts for volume control, previous/next song, ... can
      still be provided to the user while the plug-in masks the control panel. 

    The songs counter changes with every new song played and is used for example
    to display the song's name each time a new song starts.


DCDUtils_FillBuffer &52787


    Reserved for plug-ins, returns a buffer filled with samples values.
    The values are rescaled with the player volume (see SetPlayerInfo)
    to appear as if the player played at full volume.

  On entry
  
    R0 = player handle
    R1 = pointer to buffer (word aligned)
    R2 = pointer to buffer end (word aligned)

  On exit
  
    R2 = filled buffer end

  Use

    Reads sample values from the hardware on which the song is played
    (e.g. sound DMA buffers), converts them into linear stereo values
    in range [65535, -65536] but store them in the buffer as 4 bytes
    values. The buffer is filled with left and right values interlaced
    and the SWI will return with R2 pointing after the latest filled
    pair of values which may be less than the value of R2 on input
    if the hardware buffer is limited (often 208 pair of values in the
    case of sound DMA buffers).


DCDUtils_GetFullScreenPlugIn &52788


    Reserved for players, checks if a full screen plug-in is present.

  On entry

    -

  On exit
  
    R0 = handle of full screen plug-in or -1 otherwise.

  Use

    Use it to forbid some actions when a full screen plug-in is present.
    For example to prevent the default processing of F12, the activation
    of dialog boxes or new plug-ins.


DCDUtils_FillRawBuffer &52789


    Reserved for plug-ins, returns a buffer filled with samples values.

  On entry
  
    R0 = player handle
    R1 = pointer to buffer (word aligned)
    R2 = pointer to buffer end (word aligned)

  On exit
  
    R2 = filled buffer end

  Use

    Reads sample values from the hardware on which the song is played
    (e.g. sound DMA buffers), converts them into linear stereo values
    in range [65535, -65536] but store them in the buffer as 4 bytes
    values. The buffer is filled with left and right values interlaced
    and the SWI will return with R2 pointing after the latest filled
    pair of values which may be less than the value of R2 on input
    if the hardware buffer is limited (often 208 pair of values in the
    case of sound DMA buffers).


DCDUtils_StopPlugIns &5278A


    Reserved for players, closes every plug-in active for a player.

  On entry
  
    R0 = player handle

  On exit

    -

  Use

    When the player is about to terminate or to close it's window plug-ins
    should be terminated. This call will do it, by sending the message
    Message_Quit (0) to every plug-in registered for that player.


DCDUtils_UpdatePlugInsPosition &5278B


    Reserved for players, sends to every plug-in active for a player the new
    position of the player window.

  On entry
  
    R0 = player handle
    R1 = wimp poll block for Window_Open

  On exit

    -

  Use

    The tracking of the player's window position on Null window events is not
    enough to maintain plug-ins closely related to it, the plug-in will often
    not move until the user has finished dragging the player's window. This
    call is to be used when the player's window is moved and will send the
    message Message_UpdatePlugInsPosition (&52780) to every active plug-in for
    that players. It's then up to the plug-ins reposition their windows.


DCDUtils_GetBufferRate &5278C


    Reserved for plug-ins, returns the rate at which buffers are filled.

  On entry
  
    R0 = player handle

  On exit

    R1 = buffer sample rate (Hz).

  Use

    I presume you could be used in case of FFT's or similar techniques,
    thought with the small size of DMA buffers I doubt they could be applied.


DCDUtils_PlayerHasPlugIn &5278D


    Reserved for players, checks if a full screen plug-in or a windowed plug-in
    for the current player is active.

  On entry

    R0 = player handle

  On exit
  
    R1 = 1 true, 0 false

  Use

    Use it before automatic activation of plug-ins to see if none is already
    started.


DCDUtils_FillABuffer &5278E


    Reserved for plug-ins, returns a buffer filled with samples values.

  On entry
  
    R0 = player handle
    R1 = pointer to buffer (word aligned)
    R2 = pointer to buffer end (word aligned)
    R3 = flags
           bits 0-1: size in (number-1) of bytes of a sample value
           bit 2: rescale using player volume settings
           bits 3-31: reserved, should be 0

  On exit
  
    R2 = filled buffer end

  Use

    Reads sample values from the hardware on which the song is played
    (e.g. sound DMA buffers), converts them into linear stereo values.
    The values can be rescaled by the player's volume setting to give a volume
    independant aspect. The buffer is filled with left and right values
    interlaced and the SWI will return with R2 pointing after the latest filled
    pair of values which may be less than the value of R2 on input if the
    hardware buffer is limited (often 208 pair of values in the case of sound
    DMA buffers).



                                    History


Version 0.00

11-11-98 Original release.

Version 0.10

30-12-98 Totally rewritten version.

Version 0.11

06-01-99 Additional SWIs.

Version 0.12

16-01-99 Full screen plug-in start/stop: Save/Restore mode and Delirium saver.

Version 0.13

13-04-99 Full screen plug-in start/stop: Save/Restore Screen Blanker delay.

Version 0.14

23-05-99 Additional SWI to find out if there is at least a plug-in is started
         for a given player.

Version 0.15

16-08-99 I only tested small blanking delays but I fail to restore it correctly
         because ScreenBlanker_Control with opcode 3 (get delay) is in seconds
         while opcode 4 (set delay) is in centi-seconds :-((((((
24-09-99 Disable Iconbar autofronting while full-screen plug-in is running.