DSYS 2.9

Script commands
---------------

  xxx    -  Sync pos or row is not needed.
  spos   -  Effect start at this pos.
  spos   -  Effect start at this row.
  epos   -  Effect end at this pos.
  erow   -  Effect end at this row.
  handle -  An integer that identifies something.


 Misc commands
 _____________

 xxx xxx    InitKeyboardHandler
                    Initializes the keyboard handler. This will
                    disable all keys except ESC.

 xxx xxx    ExitKeyboardHandler
                    Removes the keyboard handler and reenables all keys.
                    This is done automatically before returning to DOS.

 xxx xxx    CheckVesaMode  ugh  mode1 mode2 mode2 ...
                    Check if VESA graphic modes are available and warn the
                    user if fakemode is selected or LFB not supported.
                    Demo is quitted if a mode isn't supported.
                    mode is in the form:  XRESxYRESxBITPP
                    ugh  - SOFT or HARD
                           If fakemode must be used, SOFT will start the
                           demo anyway after a few seconds. HARD will
                           wait forever untill the user presses a key.
                    You can check any number of modes.
                    E.g.  xxx xxx  CheckVesaMode  soft 320x200x16 640x480x8 
                    Note! The screen should be in textmode and the keyboard
                          handler not initialized. Put this check first
                          in the script.

 xxx xxx    SetVesaMode  width height bitpp
                    Set a VESA graphic mode.
                    If the given mode (15/16 bit) isn't supported by the
                    videocard a 8 bit fakemode is initialized if the same
                    width,height resolution is available in 8 bit.
                    If parameter -FM is given to DSYS, fakemode is always
                    used.

 xxx xxx    SetScreenMode  number
                    Set the screen mode.
                    3  = 80 x 25 textmode
                    Use ths function for going back to textmode only!

 xxx xxx    TimeScreenMode  handle
                    Use this function to get the syncronization time
                    for a screen mode needed by SyncScreenMode. 
                    Note! The module player must NOT be active when
                          this function is called! 
                    handle identifies the sync time.      

 xxx xxx    SyncScreenMode  handle
                    Syncronize the module player to a sreen mode. handle
                    is the same as in TimeScreenMode. 
                    Note! There _might_ be distortion in the music if it's
                          playing and this function is called.

 xxx xxx    Text  textstring
                    Prints the given textstring to screen. Use this
                    function in textmode only.

 xxx xxx    ScriptJMP  scriptline
                    Jump to this line in the script file.

 epos erow  WaitSYNC
                    Wait for this sync position. 

 pos row    WaitRelSYNC
                    Relative wait. Wait for this many pos and rows
                    to pass.

 xxx xxx    WaitFrames  frames
                    Wait for this many frames to pass.

 xxx xxx    ClearSCR
                    Clear screen to 0

 xxx xxx    FillSCR  R G B  mode  
                    Fill screen with color.
                     R,G,B    - [0...63] color
                     mode     - WAITFRAME or NOWAIT
                                WAITFRAME will wait for the next vertical
                                retrace before copying to screen thus
                                avoiding possible image flickering.

 xxx xxx    DoomOutput  mode
                    Specify if Doom's effects should run as standalone
                    2D effects or under the 3D engine.
                     mode   - 2D or 3D


 Palette commands
 ----------------

 xxx xxx    LoadPAL  path
                    Load a 768 byte palette and use it.

 xxx xxx    FillPAL  R G B 
                    Set all colors in the palette to this value.
                    R,G,B = [0...63]

 xxx xxx    NegPAL
                    Negate (invert) the palette.

 xxx xxx    InitFADE  path1 path2  frames  startcolor endcolor
                    Fade from palette 1 (path1) to palette 2 (path2)
                    in this many frames. Using only colors in this range.
                    Set path1 to - if you want to fade from the current
                    palette to palette 2.


 Pcx commands
 ------------

 Commands for displaying fullscreen images. Images can be any size because
 they will be stretched to the current screen width,height.

 xxx xxx    LoadPcx  handle  path
                    Load a pcx (or pcy) image (8/24 bit) to this handle.

 xxx xxx    FreePcx  handle
                    Free image with this handle.

 xxx xxx    InitMixPcxBuffer
                    Initialize (allocate) a buffer that is needed for
                    cross fading and mixing images.

 xxx xxx    ExitMixPcxBuffer
                    Deinit (free) buffer needed for cross fading and mixing
                    images.

 xxx xxx    DisplayPcx  handle  mode
                    Display the image with this handle.
                    mode  - WAITFRAME of NOWAIT
                            WAITFRAME will wait for the next vertical
                            retrace before copying to screen thus
                            avoiding possible image flickering.

 xxx xxx    DisplayMixPcx  handle1 handle2  mixvalue  mode
                    Mix the two images and display the result. Can be used
                    for "manual" cross fading.
                     handle1  - handle of image1
                     handle2  - handle of image2
                     mixvalue - integer [-8...0...8]
                                E.g.  -8 = 100% image1,   0% image2
                                       0 =  50% image1,  50% image2
                                       8 =   0% image1, 100% image2
                     mode     - WAITFRAME or NOWAIT
                                WAITFRAME will wait for the next vertical
                                retrace before copying to screen thus
                                avoiding possible image flickering.

 xxx xxx    CrossFadePcx  handle1 handle2  frames
                    Cross fade smoothly from image1 to image2 in this
                    many frames.

 xxx xxx    InitPcxFade   handle  frames  dir
                    Fading during an effect. Note! MixPcxBuffer is NOT
                    needed to use this function.
                     handle - handle to image previosly loaded with LoadPcx
                     frames - fade this many frames
                     dir    - fade direction: IN, OUT or HOLD
                               IN   - fade from image -> effect
                               OUT  - fade from effect -> image
                               HOLD - just copy image to screen



 Music commands
 --------------

 xxx xxx    InitModulePlayer
                    Initializes the module player. The player must of
                    cource be active to use the module commands below.

 xxx xxx    ExitModulePlayer
                    Turns off the module player. This is done
                    automatically before exiting to DOS. If you want
                    the -LOOP parameter to work properly, you must
                    exit the module player at the end of the script.

 Note! You can load many modules but you can only play one at a time
 due to "limitations" in the current versions of MIDAS. 

 xxx xxx    LoadModule  handle  path
                    Load module (XM, S3M or MOD) to this integer handle.

 xxx xxx    FreeModule  handle
                    Free the module with this handle.

 xxx xxx    StartModule  handle  mode
                    Start playing the module with this handle.
                    mode  - LOOP or NOLOOP

 xxx xxx    StopModule  handle
                    Stop playing the module with this handle.

 xxx xxx    SetModulePos  pos
                    Jump to this position in the module.

 xxx xxx    Vol  volume
                    Set the master volume [0...64]        

 xxx xxx    InitVolFADE  frames fromvolume tovolume
                    Fade the master volume in this many frames.
                    Volume is in the range 0...64.
                    Set fromvolume to -1 if you want to fade from
                    the current volume to 'tovolume'.

 xxx xxx    OpenChannels  n
                    Open sound channels used by module and sample playback.
                    n - number of channels to open

 xxx xxx    CloseChannels 
                    Close all sound channels.

 xxx xxx    AllocEffectChannels  n
                    Allocate auto effect channels for sample playback.
                    n - number of auto channels to allocate 

 xxx xxx    FreeEffectChannels
                    Free all auto effect channels

 xxx xxx    LoadWaveSample  handle  filename  mode
                    Load a uncompressed .WAV sample (from disk!!!).
                    handle   - sample handle
                    filename - filename
                    mode     - LOOP or NOLOOP

 xxx xxx    FreeSample  handle
                    Free a sample
                    handle   - sample handle

 xxx xxx    PlaySample  handle  pri  rate  vol  pan
                    Start playing a sample.
                    handle   - sample handle
                    pri      - sample playing priority (integer)
                    rate     - playback rate (Hz ?)
                    vol      - initial sample volume (0...64)
                    pan      - sample panning (-64...0...64)

 xxx xxx    StopSample  handle
                    Stop playing a sample.
                    handle   - sample handle



 3D Studio animation
 -------------------

 xxx xxx    InitAnim  inifile 3dsfile
                    Setup an animation with this inifile and this
                    3ds file. See anim.txt for more info.

 epos erow  DoAnim  skey ekey tpk cam pal
                    skey - Animation starts at this key.
                    ekey - Animation loops at this ending key.
                    tpk  - Time Per Key in seconds.
                    cam  - Camera name.
                    pal  - Palette file.
                    See anim.txt for more info.

 xxx xxx    ExitAnim    
                    Free animation resources.

 xxx xxx    AnimBlurr  mode
                    Turn motion blurr ON or OFF. Can be done for each call
                    to DoAnim. Note! Motion blurr must be initilatized in
                    the .INI file for this to work.

 xxx xxx    AnimBackground  pcxfile
                    Set a new background image. Can be done for each call
                    to DoAnim

 xxx xxx    InitAnimMirror  mirrhandle mapnumber camera width height aspect
                    Initialize a pseudo mirror.
                    mirrhandle - mirror handle. 0...15   (max 16 mirrors)
                    mapnumber  - internal map number. 0...255
                    camera     - camera name 
                    width      - width of the internal map in pixels
                    height     - height of the internal map in pixels
                    aspect     - aspect ratio of the camera view, float value
                    See anim.txt for more info.

 xxx xxx    AnimMirror  mirrhandle mode
                    Switch a mirror ON or OFF.

 xxx xxx    LoadImage  handle imagepath  trapath
                    Load an image to this handle with this translucent
                    table. See anim.txt for more info.

 epos erow  DisplayImage  spos srow handle  x1 y1 x2 y2  sx sy  mask proc sol
                    Setup an image segment that should be displayed
                    during an animation.
                    handle - Image handle as in LoadImage
                    x1 y1  - Upper left corner of destination window
                    x2 y2  - Lower right corner of destination window
                    sx sy  - Upper left corner in source image
                    mask   - Mask index. All colors below this value will
                             be masked out. Set to 0 if no masking.
                    proc   - PRE or POST. Tells the animation player to plot
                             the image before or after the objects has been
                             plotted to the virual buffer.
                    sol    - SOLID or TRANSP. Tells the animation player to
                             plot the image as solid or using the translucent
                             table.
                    See anim.txt for more info.

 xxx xxx    FreeImage  handle
                    Free the image with this handle.

 xxx xxx    SetAnimView  left top right bot  aspect
                    Specify the rendering window.
                    aspect sets the aspect ratio, usually 1.33333
                    E.g.   xxx xxx  SetAnimView 10 10 310 190 1.3333

 xxx xxx    RemovePreDraw  number
                    Remove animation predrawing function with this number.
                    See anim.txt for more info.

 xxx xxx    RemovePostDraw  number
                    Remove animation postrawing functiom with this number.
                    See anim.txt for more info.




Example scripts
---------------

# Simple, standard script.

 xxx xxx  CheckVesaMode     soft 320 200 8
 xxx xxx  InitKeyboardHandler
 xxx xxx  SetVesaMode       320 200 8
 xxx xxx  TimeScreenMode    0
 xxx xxx  InitModulePlayer
 xxx xxx  SyncScreenMode    0

 xxx xxx  LoadModule        0  raverain.xm
 xxx xxx  StartModule       0  noloop

 # run the effects here

 xxx xxx  StopModule        0
 xxx xxx  FreeModule        0
 xxx xxx  SetScreenMode     3
 xxx xxx  Text S i m p l e  D e m o  b y  D o o m s d a y




# Advanced script using multiple screen modes and textmode fading

 xxx xxx  CheckVesaMode     320x200x8  640x480x16
 xxx xxx  InitKeyboardHandler
 # Do a nice textmode fade
 xxx xxx  InitFADE          - pal/black.pal  70 0 255
 xxx xxx  WaitFrames        70
 # Time all used screen modes here
 xxx xxx  SetVesaMode       320 200 8
 xxx xxx  TimeScreenMode    0
 xxx xxx  SetVesaMode       640 480 16
 xxx xxx  TimeScreenMode    1
 # Start player and syncronize to the current mode
 xxx xxx  InitModulePlayer
 xxx xxx  SyncScreenMode    1

 xxx xxx  LoadModule        0  raverain.xm
 xxx xxx  StartModule       0  noloop

 # run some effects here

 xxx xxx  LoadModule        1  turbo.xm
 xxx xxx  StopModule        0
 xxx xxx  FreeModule        0
 # Initialize and sync to new screen mode here, start new module also
 xxx xxx  SetVesaMode       320 200 8
 xxx xxx  SyncScreenMode    0
 xxx xxx  StartModule       1

 # run some other effects here

 xxx xxx  StopModule        1
 xxx xxx  FreeModule        1
 xxx xxx  SetScreenMode     3
 xxx xxx  Text A d v a n c e d  D e m o  b y  D o o m s d a y

