home *** CD-ROM | disk | FTP | other *** search
/ ANews 3 / AnewsCD3.iso / C / BigAnim.doc < prev    next >
Text File  |  1999-10-06  |  10KB  |  272 lines
  1.  
  2.             *--------------*
  3.             | BigAnim v4.0 |
  4.             *==============*
  5.  
  6.  
  7.     What is BigAnim?
  8.     ~~~~~~~~~~~~~~~~
  9. BigAnim is an animation player (you guessed it!), and it's called that
  10. because it is able to display animations that are too large to be loaded
  11. into memory directly.
  12.  
  13. The most important features of BigAnim are:
  14.  
  15. o BigAnim loads the animation asynchronously, 100 KByte at a time, which
  16.   means that while it displays one 100 KByte part of the animation, it is
  17.   loading the next 100 KByte simultaneously.
  18.  
  19. o If you're using Kickstart 3.0 or later, BigAnim will use the new double-
  20.   buffering routines in graphics.library. If you're not, BigAnim will take
  21.   over the display from Intuition, to increase playback speed. However, if
  22.   you flip screens, or pull down BigAnim's screen, BigAnim will detect
  23.   this, and use the old, intuition-friendly (and slow!) routines instead.
  24.  
  25. o BigAnim has sound support.
  26.  
  27.  
  28.     Usage
  29.     ~~~~~
  30. From a CLI or shell, the usage is:
  31.  
  32.     BigAnim filename [LOADALL] [HIRES] [BLANK] [VERBOSE]
  33.                      [BUFSIZE n] [RELTIME n] [TASKPRI n]
  34.  
  35. where "filename" should refer to an ANIM type 5 or 7 animation. ANIM
  36. type 8 is not supported, due to its relative inefficiency compared to
  37. ANIM type 7. For best results, type 8 animations should be converted to
  38. type 7. BigAnim can also be used from Workbench, and the tool types
  39. are identical to the options.
  40.  
  41.  
  42.     Options
  43.     ~~~~~~~
  44.     LOADALL
  45.  
  46. Tells BigAnim to load the whole animation before starting playback.
  47. Note that the animation is loaded in chunks, and the size of these
  48. chunks can be set with the BUFSIZE keyword.
  49.  
  50.     HIRES
  51.  
  52. Forces the screen resolution to Hires/Interlace. This will only work
  53. if the original resolution was lores/nolace.
  54.  
  55.     BLANK
  56.  
  57. Blanks the mouse pointer.
  58.  
  59.     VERBOSE
  60.  
  61. BigAnim prints some info about the animation, such as screen size/depth,
  62. display modes, animation type, etc.
  63.  
  64. Example:                Explanation:
  65.  
  66. File:     Juggler            File name
  67. Picture:  320 x 200 (48000 bytes)   Picture size (width, height & bytes)
  68. Display:  320 x 200 x 6 planes        Display resolution & depth
  69. Modes:    PAL:Low Res Ham        View modes
  70. AnimType: 5                Anim type: 5, 7 (short) or 7 (long)
  71. Length:   24 frames            The number of frames in the anim
  72. Speed:    50 fps            Actual playback speed (frames/second)
  73. BufUsage: 92-98 %            Buffer utilization percentage (min-max)
  74.  
  75. Note: The actual numbers for the last four lines won't be printed until
  76. the animation has been displayed once (twice for the "Speed" and "BufUsage"
  77. numbers), simply because that information isn't available until then.
  78. The "BufUsage" numbers will not be printed if you're using the LOADALL
  79. switch.
  80.  
  81.     BUFSIZE n
  82.  
  83. Sets the buffer size to n bytes. The default is 102400 bytes (100 K), which
  84. means that BigAnim loads 100 K at a time.
  85.  
  86.     RELTIME n
  87.  
  88. Sets the playback timing, in 1/50 seconds if you're running on a PAL
  89. system, or 1/60 for NTSC systems.
  90.  
  91.     TASKPRI n
  92.  
  93. This sets BigAnim's task priority during playback. If your hard disk
  94. controller doesn't use DMA, the playback will probably be less jerky if
  95. you use a high task priority. The best value for priority is generally
  96. the same as the file system or the hard disk driver uses. Actually,
  97. TASKPRI can be used with good results even on DMA controllers: On my
  98. setup with an A590 and a Quantum LP240S, the playback becomes somewhat
  99. smoother when I use TASKPRI 11.
  100.  
  101.  
  102.     Keys
  103.     ~~~~
  104. While the animation is being played, you can press the following keys:
  105.  
  106. ESC       - Quits BigAnim (you can also use the right mouse button)
  107. Space     - Pauses the animation, or restarts if already paused
  108. N         - If paused, displays the next frame
  109. 0-9       - Changes playback speed. By pressing one of the keys 1-9 or
  110. F1-F10      F1-F9 you can directly set the RELTIME value during playback.
  111.             If you press 0 or F10, BigAnim will use the timing information
  112.             stored in the animation.
  113.  
  114.  
  115.     Environment
  116.     ~~~~~~~~~~~
  117. If you want to use certain options or settings as default, you can save
  118. them in an environment variable called BIGANIMOPTS. So, for instance, if
  119. you always want to use a buffer size of 204800 bytes, do:
  120.  
  121.     SetEnv BIGANIMOPTS BUFSIZE 204800
  122.  
  123. and BigAnim will use that instead of the built-in default of 102400 bytes.
  124. Values for BUFSIZE, RELTIME and TASKPRI set via BIGANIMOPTS can be over-
  125. ridden with the respective command line options. All options except LOADALL
  126. can be used in BIGANIMOPTS.
  127.  
  128.  
  129.     Sound support
  130.     ~~~~~~~~~~~~~
  131. BigAnim has the ability to play IFF 8SVX sounds synchronized with the
  132. animation. These sounds may be added to an animation in two steps:
  133.  
  134. 1) The sounds must be placed at the beginning of the animation file,
  135. immediately before the first ILBM picture in the animation. The file will
  136. have the following structure:
  137.  
  138. FORM ANIM
  139.    FORM 8SVX
  140.    FORM 8SVX
  141.    :
  142.    :
  143.    FORM ILBM
  144.    FORM ILBM
  145.    :
  146.    etc.
  147.  
  148. 2) If a sound is to be started at a certain frame, this frame should contain
  149. an "SCTL" chunk. It looks like this:
  150.  
  151. struct SoundControl {
  152.    UBYTE  sc_Command,    // What to do, see below
  153.           sc_Volume;    // Volume 0..64
  154.    USHORT sc_Sound,    // Sound number
  155.           sc_Repeats,    // Number of times to play the sound
  156.           sc_Channel,    // Channel(s) to use for playing (bit mask)
  157.           sc_Frequency,    // If non-zero, overrides the VHDR value
  158.           sc_Flags;    // Flags, see below
  159.    UBYTE  pad[4];    // For future use
  160. };
  161.  
  162. The sound number, starting at 1, is simply determined from the order of
  163. the sounds in the file. The "Repeats" field may be set to 0, which means
  164. that the sound will be repeated continuously.
  165.  
  166. Currently, BigAnim supports these sound commands:
  167.  
  168. #define SC_CMD_PLAY_SOUND  1    // Start playing a sound
  169. #define SC_CMD_STOP_SOUND  2    // Stop the sound in a given channel
  170. #define SC_CMD_SET_FREQVOL 3    // Change frequency/volume for a channel
  171.  
  172. Sound flags:
  173.  
  174. #define SCB_NOINTERRUPT 0    // Play the sound, but only if
  175. #define SCF_NOINTERRUPT (1<<0)    // the channel isn't in use
  176.  
  177. Sometime soon (TM), I will release a new version of my animation tool
  178. "BuildAnim", that will be able to build animations with sounds, and add
  179. sounds to existing animations.
  180.  
  181.  
  182.     Additional info
  183.     ~~~~~~~~~~~~~~~
  184. o BigAnim supports CMAP chunks internal to the animation, and changes the
  185.   screen colors accordingly. 
  186.  
  187. o BigAnim uses the RelTime field of the ANHD chunk to decide how much
  188.   delay to put between frames. You can override this value by specifying
  189.   a new value with the RELTIME keyword, or by pressing a number key during
  190.   playback.
  191.  
  192. o BigAnim uses two sets of specially optimised decompression routines,
  193.   for processors with and without instruction cache.
  194.  
  195.  
  196.     How to choose the best buffer size
  197.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  198. To maximize playback speed, do this: If you have enough memory in your
  199. Amiga to load the entire animation, use the LOADALL switch. This will
  200. lead to the fastest possible playback. If you don't have that much
  201. memory, you can try different buffer sizes with the BUFSIZE keyword.
  202. Tip: If you use the VERBOSE option, BigAnim will measure the playback
  203. speed, so you can easily see how different buffer sizes affect playback.
  204. Also, the "BufUsage" numbers will tell you how well the buffers are
  205. utilized during playback.
  206.  
  207. When choosing buffer size, please keep these facts in mind:
  208.  
  209. 1. Due to the asynchronous nature of BigAnim's loading method, using
  210. the largest possible buffer size may not give the fastest playback.
  211.  
  212. 2. Certain combinations of file size and buffer size should be avoided.
  213. An example: If you use a buffer size of 300 KBytes with an animation
  214. that's 1000 KBytes long, then the first three reads will read 300 KBytes
  215. each, but the fourth will only read 100 KBytes. This is clearly not
  216. optimal. It would be much better to use a buffer size of 250 or 334
  217. KBytes (or just a little bit more, to be on the safe side). So, in
  218. cases when the last read of an animation is less than half as long as
  219. the others, BigAnim will print a warning message: "non-optimal buffer
  220. size".
  221.  
  222. There are two common problems often encountered while trying to find the
  223. ideal settings:
  224.  
  225. Common problem #1: Sometimes the playback stops for a while, then continues.
  226.  
  227. Reason: Either (1) your hard disk cannot read fast enough to keep up with
  228. the playback, (2) y