home *** CD-ROM | disk | FTP | other *** search
/ Graphics 16,000 / graphics-16000.iso / msdos / utils / fbm2fl03.lha / fbm2fli.doc next >
Text File  |  1993-11-16  |  13KB  |  274 lines
  1. ===========================================================================
  2. /* fbm2fli.doc */
  3.  
  4. Copyright (C) 1993 by Klaus Ehrenfried. 
  5.  
  6. Permission to use, copy, modify, and distribute this software
  7. is hereby granted, provided that the above copyright notice appears 
  8. in all copies and that the software is available to all free of charge. 
  9. The author disclaims all warranties with regard to this software, 
  10. including all implied warranties of merchant-ability and fitness. 
  11. The code is simply distributed as it is.
  12.  
  13. ===========================================================================
  14.  
  15. About FBM2FLI:
  16.  
  17. The program `fbm2fli' allows to generate FLI-animations  
  18. from series of single images. `fbm2fli' uses the standard function from the 
  19. FBM library to read the image files. Thus it can handle various 
  20. file formats including GIF, SUN-raster and FBM. See the FBM 
  21. documentation about which other graphic formats are supported. 
  22. The program requires that the images are mapped and have 8 bit per pixel. 
  23. In contrast to the very popular "DTA" program for MS-DOS the 
  24. quantization of true-color images (e.g. POV output images) 
  25. has to be done separately. `fbm2fli' simply puts the prepared images 
  26. together. If true-color pictures should be processed, the 
  27. the quantization has to be done before `fbm2fli' is called.
  28. For example the quantization can be done by the `fbquant' utility 
  29. included in the FBM package or by the `fboctree' program (see `fboctree.doc').
  30. Together with the FBM package it should be possible 
  31. to deal with most of the graphic standards and file formats. 
  32. I have tested `fbm2fli' on a PC running Linux and on SUN workstations and
  33. I used version 1.0 and 1.2 of the FBM package. 
  34.  
  35. ===========================================================================
  36.  
  37. Usage:
  38.  
  39. fbm2fli [options] list animation
  40.  
  41. Parameters:
  42.  
  43. "list" is the name of a file which contains line by line a list of names 
  44. of image files which are merged together in the given order. 
  45. "animation" is simply the name of the generated animation file. 
  46.  
  47. Options overview:
  48.  
  49.     -b*    :    border color = *
  50.     -D    :    double buffering
  51.     -m*    :    map-file name = *
  52.     -O    :    generate FLI with old format
  53.     -ox*    :    horizontal origin = *
  54.     -oy*    :    vertical origin = *
  55.     -rx*    :    horizontal resolution = *
  56.     -rx*    :    vertical resolution = *
  57.     -s*    :    animation speed = *
  58.  
  59. Options details:
  60.  
  61. -b* (border color):
  62.   In regions where no input data is available, because the input image 
  63.   doesn't cover the hole display area of the animation, 
  64.   the pixel value is set to the given value. By default zero is used. 
  65.   See also the "-ox" option. 
  66.  
  67. -D (double buffer):
  68.   By default the generated FLI chunks only hold the update information 
  69.   with respect to the last frame. If the "-D" option is given, the FLI 
  70.   chunks additionally provide the update information with respect 
  71.   to the frame before the last. In both cases the FLI animations 
  72.   work with standard players. The additional update information is useful 
  73.   for players which use double buffer technique (see remark below). 
  74.   If you have not such a player this option is useless.
  75.  
  76. -m* (map file):
  77.   The color table of the given image file is used for all images
  78.   in the animation. The original color table in the animated images is 
  79.   ignored. The map file itself becomes not part of the animation. 
  80.   Only its color table is used. This option is useful in many 
  81.   circumstances. E.g: it is possible to change the colors in the 
  82.   hole animation simply by manipulating the table of one file. 
  83.  
  84. -O (old format)
  85.   An old format FLI with Magic Number 0xAF11 is generated. Instead of the
  86.   DELTA_CHUNKS (7) the old LC_CHUNKS (12) are used and COLOR_CHUNKS (11) 
  87.   instead of COLOR_256_CHUNKS (4). Some older players cannot handle newer FLI 
  88.   animations with the Magic Number 0xAF12. This option allows to generate 
  89.   FLIs for this players. When the "-O" option is given the default 
  90.   resolution is set to 320x200. Otherwise 640x480 is used. 
  91.  
  92.   Note: Often the new format FLIs are called `FLC'-files but I use the name
  93.   `FLI' for both the new and the old standard.
  94.  
  95. -ox* (horizontal position):
  96.   By this option the horizontal position of the left border of the 
  97.   input images in the display area of the animation is controlled. The value 
  98.   gives the number of pixels from the left border of the displayed area to
  99.   the left border of the image. By default the input images are centered 
  100.   in the display area. If the width of an input image is less than the 
  101.   chosen resolution, borders are inserted on both sides of the image 
  102.   symmetrically. The border area is filled with the pixel value given 
  103.   by the "-b" option. If the width of an input image has a higher value 
  104.   than the chosen resolution, an equal amount of pixels is cut off from 
  105.   both sides of the input image. Thus, when the size of the animated 
  106.   images varies, the left border of the images is at different locations 
  107.   in the display. If the "-ox" option is given, the automatic centering 
  108.   is disabled and the left border of the input image is kept fixed at the 
  109.   given horizontal position. This can be used to place small input images 
  110.   at a certain position in the display, or to animate only a certain section 
  111.   of larger input images. 
  112.  
  113. -oy* (vertical position):
  114.   Same as "-ox" but for the vertical position. The value gives the number 
  115.   of pixels between the upper border of the display area and the upper 
  116.   border of the input image.
  117.   Note: With "-ox" and "-oy" also negative values are allowed. Then parts 
  118.   of the input images are outside the display area.
  119.  
  120. -rx* (horizontal resolution):
  121.   With this option the horizontal resolution can be modified. The value can 
  122.   range from 10 to 1280. If an odd value is given, 1 is added automatically. 
  123.   I do not know if all players (especially the players which only handle 
  124.   old format FLIs) can deal with all resolutions. In principle the VGA
  125.   resolution 320x200 should always work. For players which can play the 
  126.   FLIs with Magic Number 0xAF12 at least 640x480 should work also. When 
  127.   strange numbers are used nothing is guaranteed. 
  128.  
  129. -ry* (vertical resolution)
  130.   Like "-rx*" but for the vertical direction. In contrast to "-rx*" here
  131.   also odd numbers are accepted. Maximum value is 1024.
  132.  
  133. -s* (speed):
  134.   In the header of the FLI file a default value for the animation speed
  135.   is stored (Actually not directly the speed but the delay time between 
  136.   two frames is stored).
  137.   This default value is used by some players if no other speed
  138.   is set at playing time. The meaning of the value depends on the format 
  139.   of the FLIs. For old format FLIs the value gives the number of video 
  140.   ticks between two frames. If "-s*" is omitted a default of 5 is used. 
  141.   For new format FLIs the delay between two frames is given in 1/1000 
  142.   seconds rather than video ticks. In this case a default of 72/1000 
  143.   seconds is used. This results in approximately 15 frames per seconds. 
  144.   In both cases a higher value reduces the speed. 
  145.  
  146. ===========================================================================
  147.  
  148. Examples:
  149.  
  150.   Pathological example to explain the use of "-ox", "-oy", "-rx" and "-ry": 
  151.   -------------------------------------------------------------------------
  152.   We have a series of images with different resolutions. We want a 36x10 
  153.   resolution for the FLI animation. We want that the images are not 
  154.   automatically centered, but that the upper-left corner of the images is 
  155.   located at the position (6,2) in display area. The origin (0,0) of the 
  156.   coordinate system of the display area is located in the upper-left corner.
  157.   The name of the list file is "example.lst" and the name of the generated 
  158.   FLI file is "example.fli". We type:
  159.  
  160.       fbm2fli -rx36 -ry10 -ox6 -oy2 example.lst example.fli
  161.  
  162.   The following figure shows the resulting location for an input image with 
  163.   9x5 pixels: 
  164.  
  165.       0123456
  166.       |< - >|
  167.  
  168.       ------------------------------------  --0
  169.       |                                  |    1
  170.       |     ---------                    |  --2
  171.       |     | input |                    |
  172.       |     | image |                    |
  173.       |     | 9x5   |                    |
  174.       |     ---------                    |
  175.       |                                  |
  176.       |                                  |
  177.       ------------------------------------
  178.             ( Display area 36x10 pixel )
  179.  
  180.  
  181.   More reasonable example to explain the use of "-ox", "-oy", "-rx" and "-ry": 
  182.   ---------------------------------------------------------------------------
  183.   We have a series of 768x512 images produced by someone else or by a 
  184.   commercial software. We want to animate these images, but we want that 
  185.   the top 20 lines of each image are cut off, because there occurs something 
  186.   disturbing (advertisement or so). 
  187.   Again the name of the list file is "example.lst" and the name of the 
  188.   generated FLI file is "example.fli". We type:
  189.  
  190.       fbm2fli -rx768 -ry492 -oy-20 example.lst example.fli
  191.  
  192.   Note 1): 492 = 512 - 20.
  193.   Note 2): Also negative values are allowed with the options "-ox" and "-oy".
  194.            Of course, if a negative value is given the upper-left corner 
  195.            of the images is outside the display area.
  196.  
  197.   Example to explain the use of "-m": 
  198.   -----------------------------------
  199.   We have a series of images and all have the same color table. But the 
  200.   used colors are ugly and it is much work to change all color tables. 
  201.   Then we generate a special image (using a color-table editor) 
  202.   which has a better color table. We assume that the name of this file is 
  203.   "nice_colors.gif".
  204.   Again the name of the list file is "example.lst" and the name of the 
  205.   generated FLI file is "example.fli". We type:
  206.  
  207.       fbm2fli -mnice_colors.gif example.lst example.fli
  208.  
  209. ===========================================================================
  210.  
  211. Remarks about double buffering (PC players only):
  212. [About the sense of the "-D" option]
  213.  
  214. One special feature of `fbm2fli' is that the program can generate 
  215. animations for players which use double buffering. The advantage of 
  216. players which use double buffering is that they allow a smooth 
  217. and undisturbed display even in cases where almost all pixels are 
  218. changing from one frame to the next. Most players write directly to 
  219. the visible part of the video memory. The FLI-file holds the update
  220. information for the next frame. The player waits until the beginning 
  221. of the vertical blank period of the video signal (this is the time 
  222. in which the electron beam in the monitor moves from the bottom to 
  223. the top) and then it starts to update the video memory. If too much 
  224. pixels have to be updated or the access to the video memory it too 
  225. slow (ISA bus and higher resolution ...) one gets disturbances in the 
  226. display. The reason for this is that an image is shortly visible on 
  227. the screen which has a part at the top already updated to the next 
  228. frame but the remainder at the bottom still shows the information from the 
  229. previous frame. Only if the player writes faster to the video 
  230. memory than the video chip reads this memory one gets 
  231. an undisturbed animation. But this can only be archived by very fast 
  232. graphic boards (50 MHz local bus and low resolution) or by animations where 
  233. not more than a certain amount of new pixels has to be updated 
  234. between the frames. 
  235. Double buffering simply overcomes these restrictions by using a 
  236. second buffer and writing to an invisible part of the video memory. 
  237. When the update of one buffer is complete the player switches the 
  238. display to the ready buffer and starts to process the next frame in 
  239. the other -- now invisible -- buffer. 
  240. But in this case the player needs the update information with 
  241. respect to the frame which previously was located in the same 
  242. buffer. And this frame is not the last one, which was processed in 
  243. exactly the other buffer, but the frame before the last. 
  244.  
  245. ===========================================================================
  246.  
  247. Installation:
  248.  
  249. Necessary requirement for `fbm2fli' is the correct installation of 
  250. the FBM package from Michael Mauldin (mlm@nl.cs.cmu.edu).
  251. Is is available via FTP as "nl.cs.cmu.edu:/usr/mlm/ftp/fbm.tar.Z".
  252. Probably some changes in the makefile are required to indicate 
  253. where the FBM stuff is located on your machine and which compiler 
  254. is used. I have tested the code only with GCC 2.*.*. Because 
  255. I didn't use any dirty tricks it should also work with other 
  256. standard compilers.
  257.  
  258. ===========================================================================
  259.  
  260. History:
  261.    25-April-93    Initial Release.
  262.    28-May-93      Corrected one bug in fppcolor.c. Now the -m option
  263.                   should work correctly. 
  264.    08-Oct-93      Added the file fpplc.c. Now also old format FLIs can 
  265.           be generated.
  266.           Some other changes:
  267.           - New command line syntax
  268.           - More flexible way to choose resolution
  269.           - Internal compression slightly improved
  270.  
  271. -- Klaus Ehrenfried (klaus@spock.es.go.dlr.de)
  272.  
  273. ===========================================================================
  274.