home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / bbs / ff779.lha / FF779 / AAP_AAC / AAP.Doc < prev    next >
Text File  |  1992-12-06  |  15KB  |  455 lines
  1. 10. Oct 1992       Docfile for AAP      version 1.2 (1.st public release)
  2.  
  3.   ** Table of contents in this docfile **
  4.  
  5. 1. .... FUNCTIONAL OVERVIEW
  6. 2. .... INSTALLATION
  7. 3. .... USAGE (CLI-OPTIONS / WORKBENCH CALL)
  8. 4. .... AAP KEY AND MOUSE FUNCTIONS
  9. 5. .... USING SCRIPT FILES
  10. 6. .... PERFORMANCE
  11. 7. .... BUGS
  12.  
  13.  
  14. 1. FUNCTIONAL OVERVIEW
  15.  
  16. AAP (AmigaAnimPlayer) offers the following features:
  17.  
  18.     -   show animations  (IFF ANIM_5, ANIM_7)
  19.         (For a description of the new ANIM7 fileformat
  20.         see Anim7.doc file.)
  21.  
  22.     -   show pictures    (IFF ILBM)
  23.  
  24.     -   show (long) sequences of animations and/or pictures
  25.         (using a script file)
  26.  
  27.     -   operates from memory (preload) and/or from disk
  28.  
  29.  
  30. 2. INSTALLATION
  31.  
  32. AAP needs no additional files or libraries to run.
  33.  
  34. Copy the executable and the icon (AAP and AAP.info)
  35. to your Harddisk where you like.
  36.  
  37. AAP runs on AMIGAs with Kickstart 1.3 and higher.
  38.  
  39.  
  40. 3. USAGE (CLI-OPTIONS / WORKBENCH CALL)
  41.  
  42. For workbench call you need to select one icon (of a aap-script
  43. or a picture or an animation) and then shift-double-click the AAP icon.
  44. You may set AAP as the default tool in your aap-scripts and
  45. call AAP with double-click on the script icon.
  46.  
  47. When any error occurs, AAP makes a DisplayBeep end exits.
  48.  
  49. The call from cli has 2 advantages:
  50.  
  51. - In case of any errors AAP displays error messages in the cli window.
  52.  
  53. - You may specify some options
  54.  
  55.  
  56. usage:
  57.     aap [-switches] anim | picture | script
  58.  
  59. All the switches are optional.
  60.  
  61.     [-d]    Play from diskfile
  62.         The -d option allows you to play anims that are much
  63.         larger than your free memory.
  64.         (A very fast Harddisk (> 800 kB/sec) is recommanded)
  65.         .. see also _LOAD_OFF script command.
  66.  
  67.     [-m]    Preload file into memory.               (default)
  68.         This option is the opposite of the -d option.
  69.         .. see also _LOAD_ON script command.
  70.  
  71.     [-t]    Enable other tasks while playback
  72.         Normally AAP stops all other tasks while playing the
  73.         animations to get the maximum playbackrate.
  74.         Sometimes it is desired to run other tasks
  75.         (probably soundtasks) at the same time.
  76.         (The interrupts are NOT affected by this option)
  77.  
  78.     [-w]    Wait for left mouse at first frame.
  79.         After checking and preloading all anims and pictures
  80.         AAP normally begins the playback. With this Option AAP
  81.         shows the first frame and waits 'standby' for a
  82.         doubleclick (left mouse button) before starting the
  83.         animation sequence.
  84.  
  85.         This option is useful for recording your anims on Video.
  86.  
  87.     [-l]    Type script while analyzing it.
  88.         All lines of the script are displayed (on stdout).
  89.         Remark lines are prefixed with the word 'REMARK'.
  90.  
  91.         This option is useful for debugging yor scripts.
  92.  
  93.     [-!]    Check performance by flashing color0 at each frame.
  94.         green:  frame in time,
  95.         red:    frame is late.
  96.  
  97.     [-snnnn]    Speed in jiffies
  98.         This option sets the playback rate for anims in jiffies.
  99.         The rate must be a positive integer following immediate
  100.         behind the 's' letter!!
  101.         Further options must be separated by blank.
  102.         .. see also _SPEED script command.
  103.  
  104.     [-cxxxx]    Codeword for crypted files
  105.         For crypted files you need to specify a 4 character
  106.         codeword (any numbers and letters).
  107.         The codeword must follow immediate behind the 'c'
  108.         letter!!
  109.         Further options must be separated by blank.
  110.  
  111.         (This option is not available in the public domain
  112.          version of AAP.)
  113.  
  114.  
  115. Examples:
  116.  
  117.     aap -d -s8  dh0:anims/my_anim_file
  118.  
  119. Plays the animation 'my_anim_file' directly from the harddisk
  120. drawer dh0:anims.
  121.  
  122. The playbackspeed is set to 8 jiffies per frame. (The frame
  123. timing values stored in the ANHD and DPAN chunks of
  124. 'my_anim_file' are ignored because of the -s option.)
  125.  
  126.     aap -m my_script_file
  127.  
  128. Plays anims and pictures that are listed in 'my_script_file'.
  129. This anims and pictures are preloaded into memory because the
  130. preload mode is turned on by -m option. (With _LOAD_OFF and
  131. _LOAD_ON commands you may control preload mode for each file
  132. in the script.)
  133.  
  134.  
  135. 4. AAP KEY AND MOUSE FUNCTIONS
  136.  
  137.     key                     function
  138.     -----------------------------------------------------------
  139.     ESC             Terminate immediate.
  140.     CursorKeys      Scroll the display in direction of the
  141.                     cursor arrows.
  142.                     (Modifies the view offsets of the Display)
  143.                     Useful to center the display when using
  144.                       overscan pictures.
  145.     BLANK           (Re)Set the view offsets of the display
  146.                       according to the systems preferences.
  147.     CTRL            ignore frame timing, and play with
  148.                       maximum speed.
  149.  
  150.  
  151.     all other Keys may be used for script-defined interactions
  152.     Valid Keynames are:
  153.       A, B,   ... Z,
  154.       0, 1,   ... 9,
  155.       10_0, 10_1, .... 10_9, 10_MINUS, 10_PLUS
  156.       F1, F2, ... F10,
  157.       ESC, DEL, TAB, BACKSPACE, HELP, CTRL, CR, ENTER
  158.       TILDE, DOT, KOMMA, MINUS, PLUS, SPACEBAR
  159.       UP, DOWN, LEFT, RIGHT
  160.       LEFT_SHIFT,  LEFT_ALT,  LEFT_AMIGA
  161.       RIGHT_SHIFT, RIGHT_ALT, RIGHT_AMIGA
  162.  
  163.       ANY_KEY    /* value for any key */
  164.  
  165.  
  166.  
  167.     (see _KEY_JUMP, _KEY_WAIT and _KEY_BREAK script commands)
  168.  
  169.  
  170.     mouse                   function
  171.     -----------------------------------------------------------
  172.                     The mouse pointer is made invisible while
  173.                       playback.
  174.     RIGHT Button    Terminate immediate.
  175.     LEFT  Button    Stop current frame or continue with next
  176.                       frame when already stopped.
  177.                       (toggle switch)
  178.  
  179.  
  180. 5. USING SCRIPT FILES
  181.  
  182. Both programs AAP and AAC use the same kind of scriptfiles.
  183. Scripts are used to assemble animation sequences or picture
  184. slide shows.
  185. Scripts are line-structured ASCII files and can be made with
  186. any editor.
  187.  
  188. -   There can be only ONE filename or command in a single line.
  189.  
  190. -   Files with binary data are not accepted as script.
  191.  
  192. -   Script files are not case sensitive.
  193.  
  194. -   Blank lines, or lines starting with the semicolon ';' are
  195.     remarklines.
  196.  
  197. -   All lines that are no command or no remarklines must
  198.     contain the name of a picture or animation file.
  199.     Filenames with Blanks must be embedded in Quotes like this:
  200.     "SPACE PICTURE"
  201.  
  202. If the file is an animation file the following trailing options
  203. are available:
  204.  
  205.     -C[J][times]    or
  206.     -L[J][times]
  207.  
  208.     C   option is for continous loop mode.
  209.         This mode assumes that frame#0 and frame#1 are repeated
  210.         as the last two frames in the anim file. (Dpaint saves
  211.         anims in this convention.)
  212.         According to this, the frames#0 and #1 are only
  213.         displayed at the first loop.
  214.  
  215.     L   option is for full loop mode.
  216.         In this mode frame#0 and #1 are displayed in each loop.
  217.         (Unpacking frame#0 and #1 usually takes more cpu-power
  218.          than the other frames in the animation.)
  219.  
  220.     J   Option is for continous joining of an animation to the
  221.         previous one.
  222.         This mode assumes that frame#0 and #1 are the same as
  223.         the last 2 frames of the previous animation and begins
  224.         with frame#2 (delta to #0) and frame#3 (delta to #1).
  225.         In other words: the 'slow' frames #0 and #1 are not
  226.         displayed when option J is used.
  227.  
  228.         WARNING: both anims must be from same display size
  229.                  (width, heigth, depth, viewmode) and must use
  230.                   the same palette (colors).
  231.                  frame#0 and frame#1 MUST be exactly the same
  232.                  frames as the last 2 frames from the previous
  233.                  animation.
  234.                  If NOT the result is a trashed display!!
  235.  
  236.     times .. integer value how many times to play this anim.
  237.         default value is 1.
  238.  
  239.  
  240. Available Commands:
  241.  
  242.     _PAUSE  [time]
  243.         Wait additional time (in jiffies) before displaying the
  244.         next frame.
  245.  
  246.     _SPEED  [time]
  247.         Set playback rate (in jiffies) for all following
  248.         animations. (1 is maximum speed.)
  249.         _SPEED without parameters (or 0) will use the playback
  250.         rates that are defined in the animfiles. (Playbackspeed
  251.         can also be set by -s option at CLI call)
  252.  
  253.  
  254.     _PIC_TIME [time]
  255.         Set default time (in jiffies) for single pictures.
  256.  
  257.     _LOAD_ON
  258.         Set preload mode.
  259.  
  260.     _LOAD_OFF
  261.         Clear preload mode.
  262.  
  263.     All picture/anim files found between _LOAD_ON and _LOAD_OFF
  264.     (or end of ScriptFile) are loaded into memorybuffers before
  265.     the first frame is displayed.
  266.  
  267.  
  268.     Pictures and anims can appear in the script as often as
  269.     desired, but they are loaded only ONCE to save memory.
  270.  
  271.         Example:
  272.  
  273.             _LOAD_OFF
  274.             pic1
  275.             pic2
  276.             _LOAD_ON
  277.             pic1
  278.             pic3
  279.             pic1
  280.  
  281.     In the script above is a slide show to display pictures in
  282.     order 1,2,1,3,1. pic1 and pic3 were preloaded into memory
  283.     buffers but pic2 is displayed from disk.
  284.  
  285.     The initial preload mode can be set by the CLI option -m
  286.     and cleared with option -d. This initial mode is valid
  287.     until the first scriptline with _LOAD_ON or _LOAD_OFF
  288.     statement.
  289.  
  290.     _BEG_LOOP [times]
  291.     _END_LOOP
  292.         Define begin and end segment of the script that is to
  293.         repeat.
  294.         times is an optional integer. Default is 32000 times
  295.         ('endless loop'). Loops can be nested.
  296.  
  297.     _LABEL labelname
  298.         this directive marks a location in the script.
  299.         it is used as destination for _KEY_JUMP commands.
  300.  
  301.     _KEY_BREAK      *)
  302.         After this Command is executed any key breaks the playback
  303.         of the current anim (or picture delay time) and the next
  304.         script statement is executed.
  305.         (This may be useful for fast _KEY_JUMP interactions)
  306.  
  307.     _KEY_WAIT [keyname]      *)
  308.         Wait until the specified key is pressed.
  309.         the keyname ANY_KEY (or omitting the keyname)
  310.         pauses the script execution until any key is pressed.
  311.         (see ... for valid keynames)
  312.  
  313.     _KEY_JUMP labelname [keyname]   *)
  314.         This Command can branch the execution of the script
  315.         to the marked location in the script with the same labelname.
  316.         (see also _LABEL command)
  317.  
  318.         If the keyname is omitted
  319.            an unconditional Jump is performed.
  320.         If the keyname is ANY_KEY
  321.            the Jump is performed when any key is pressed at this time.
  322.         If the keyname is a valid keyname
  323.            the Jump is performed when the specified key is pressed.
  324.  
  325.         (see ... for valid keynames)
  326.  
  327.  
  328.     _ADRESS         *)
  329.         Cmd not implemented (reserved)
  330.  
  331.     _MSG            *)
  332.         Cmd not implemented (reserved)
  333.  
  334.     _VIEW_DX [ofs]  *)
  335.     _VIEW_DY [ofs]
  336.         Horizontal/vertical adjust of the display.
  337.         ofs is an optional integer value in pixels. (Default or
  338.         value 0 will use the display offsets from the systems
  339.         preferences.)
  340.  
  341.     _EXIT [rc]
  342.         Exit, and set returncode to rc.
  343.         rc is an optional integer (rc default is 0).
  344.  
  345.  
  346.     *) .. Command is ignored in AAC
  347.  
  348.  
  349.     Example:
  350.  
  351.         _BEG_LOOP
  352.         dh0:anims/my_anim_file -c3
  353.         dh0:anims/your_anim_file -L5
  354.         _END_LOOP
  355.  
  356.  
  357.     Will display 'my_anim' 3 times in continous mode then
  358.     'your_anim' 5 times (showing all frames every time) and
  359.     then repeat this sequence of my and your anim again and
  360.     again (= 32000 times).
  361.  
  362.  
  363.  
  364. 6. PERFORMANCE
  365.  
  366. The playback speed of frames depends on following facts:
  367.  
  368.     -   displaying frames directly from a diskfile usually
  369.         takes more time than displaying preloaded frames.
  370.  
  371.     -   Pictures with RLC-packed body (std. IFF as written by
  372.         DPaint) may load faster from disk than unpacked ones,
  373.         but unpacked IFF pictures can be displayed faster
  374.         when they are only moved from a buffer to the display-memory.
  375.         (A simple long-word based blockmove is much faster
  376.          than a byte-oriented unpack algorithm.)
  377.  
  378.     -   Anim files usually display the frames faster than
  379.         sequences of single pictures. (Because only the changed
  380.         displaydata must be moved.)
  381.  
  382.     -   ANIM5 versus ANIM7
  383.         ANIM5 is an established Standard on the Amiga, ANIM7 is
  384.         (for now) only supported by AAP and AAC.
  385.  
  386.         ANIM5 uses a normal ILBM Picture as first frame and
  387.         delta informations for all following (DLTA) frames.
  388.         DLTA frames are packed 'byte oriented' with vertical
  389.         run length encoding and skip opcodes. This gives good
  390.         compressing rates, but not optimal playbackrates. (The
  391.         full power of 68030 turbo machines can not be used when
  392.         moving single bytes.)
  393.  
  394.         In ANIM7 the packer code (AAC) can decide if short or
  395.         long data should be used. The first frame can be a
  396.         normal ILBM picture or a DLTA to an empty frame. (The
  397.         empty frame is not stored and has all bitplanedata set
  398.         to zero.)
  399.         ANIM7 uses seperated opcode(bytes) and data(short/long)
  400.         lists to represent delta informations. Similar to ANIM5
  401.         it uses vertical run length encoding with skip opcodes.
  402.         This gives acceptble packing rates and enables higher
  403.         playback rates than ANIM5. (Especially when preloaded
  404.         into 32 bit organized fast RAM, found on turbo Boards
  405.         or AMIGA 3000.)
  406.  
  407.  
  408. AAP Performance Notes:
  409.  
  410. All routines that handle with BitPlane data are coded in
  411. Assembler, optimized for speed. Disk-IO is coded as one seek
  412. and one read instruction per frame while playback.
  413.  
  414. Testvalues represent the time (in jiffies) to produce one frame
  415. with a 68000, 7MHz (68030, 16MHz).
  416.  
  417. Performancetests depend very much on the packing rate of
  418. the used frames.
  419. The subjective Results of the Tests are:
  420.  
  421. Configuration:
  422.     CPU 1: 68000, 7MHz,
  423.     CPU 1: 68030, 16MHz,
  424.     RAM  : 1MB CHIP-RAM + 1.5 MB RangerMem + 2MB 32-Bit RAM
  425.     DH0  : Quantum 120 LPS (SCSI II)
  426.     SQ0  : Syquest 44MB
  427.  
  428.     - When using the 68000 CPU Playback-timing Problems starting at
  429.       5Plane LO-RES INTERLACE Anim5 Playback from RAM.
  430.       The Playbackrates are acceptable (10-20 f/sec) when using Anim7 Format
  431.       (short or long)
  432.       HI_RES INTERLACE Anims playback to slow.
  433.  
  434.     - When using the 68030 CPU Playback-timing Problems starting at
  435.       HI_RES INTERLACE Anims, but the playbackspeed is
  436.       acceptable in Anim7 (long) Format combined with 32Bit RAM.
  437.       (one reason may be the extensive DMA used by the Display
  438.       in this Graphic Mode)
  439.  
  440.     - The SQ0 Drive is to slow for real Disk Animation. Even in LO-RES.
  441.  
  442.     - The DH0 Drive enables Disk Animation in LO-RES without timing
  443.       Problems and acceptable results when using LO-RES INTERLACE.
  444.       HI-RES INTERLACE Anims are remarkable slowed down.
  445.  
  446. 7. BUGS
  447.  
  448. - When Scrolling Hi-Res Interlaced Displays (using the Cursor Keys)
  449.   some portions of the Display may disappear.
  450.  
  451. - When AAP is called with -t option and the left mousebutton
  452.   was pressed all keyboard and mouse actions affect the hidden
  453.   windows of other applications running behind.
  454.   (Intuition does't notice the AAP managed screen)
  455.