home *** CD-ROM | disk | FTP | other *** search
/ Chip 1999 March / Chip_1999-03_cd.bin / zkuste / delphi / D1234C1 / TGIFIMAG.ZIP / ReadMe.txt < prev    next >
Text File  |  1998-07-16  |  21KB  |  450 lines
  1. _____________________________________________________________________
  2. |                                                                   |
  3. | TGIFImage 2.9                                                     |
  4. |                                                                   |
  5. | Delphi & C++Builder VCL Component for manipilating GIF files      |
  6. |                                                                   |
  7. ---------------------------------------------------------------------
  8. |                                                                   |
  9. | Theodor Kleynhans                                                 |
  10. |                                                                   |
  11. | theodor@sulako.com                                                |
  12. | http://www.sulako.com/                                            |
  13. |                                                                   |
  14. ---------------------------------------------------------------------
  15.  
  16. Hi folks!
  17.  
  18. Greetings from a sunny South Africa (Cape Town to be precise).
  19.  
  20. Well, after downloading many a free component I felt obliged to return the favour. I was
  21. looking for a GIF component myself but found out they're all about $10,000 (well, not really,
  22. but almost...).
  23.  
  24. Thus the TGIFImage component was born. From the outset I decided to release it as Freeware
  25. (although I still prefer to keep the source). So anybody who thinks the component is worthwhile
  26. is free to use it in any way they please.
  27.  
  28. All I ask is that you EMail me to tell me what you think of it (good or bad) and whether you
  29. would like to see any features added or removed. I'd also appreciate it if, when it chokes on
  30. an image, you send me a copy of the image and, if possible, a short description of your
  31. implementation of the component. I'll then fix the bug as soon as possible and send you an
  32. update.
  33.  
  34. So many users asked for a way to get hold of the source, I eventually decided to make it
  35. available for $50. You can order it on-line using a secure SSL 3.0 server at the following
  36. URL: http://www.shareit.com/programs/100318.htm.
  37. If you'd prefer not to give out credit-card information, there are also other ways to pay.
  38. (Also listed at the above URL).
  39.  
  40.  
  41. Now, a few features of TGIFImage:
  42.  
  43. * Fully compliant with the GIF 87a and 89a standards
  44.   Will also try to decode unknown versions, as recommended in the specifications.
  45.  
  46. * Recognizes all documented extension blocks
  47.   Plain Text blocks and Unknown Application blocks are recognized but skipped over.
  48.  
  49. * Can decode and display animated GIF's
  50.   Supports the Netscape Loop-block implemented by apps such as GIF Construction Set and MS GIF
  51.   Animator. Also supports the "Remove To Previous Image" animation option not even supported by
  52.   Netscape.
  53.  
  54. * Can decode and display transparent GIF's
  55.   Animated GIF's can also be transparent. Even when images are tiled or stretched they still keep
  56.   their transparency.
  57.  
  58. * Can decode and display interlaced GIF's
  59.   Animations and Transparent GIF's can also be interlaced.
  60.  
  61. * Can save to GIF files as well
  62.   This enables you to compress those bulky Bitmaps. Do the following test: Use the sample
  63.   application to load a GIF animation and then save it under another name (again using the
  64.   sample app). Now compare the file sizes... TGIFImage optimized the file size as much as
  65.   possible without sacrificing image quality. I tried it on a sample GIF, and it
  66.   shrunk from 25,821 bytes to 19,029 bytes. Not so much in itself, but if you add all the
  67.   images on eg. your web site together, it can make quite an impact on download performance.
  68.  
  69. I think that about covers everything the GIF standard currently supports. If I've missed
  70. anything, please let me know and I'll implement it (or at least try to...).
  71.  
  72.  
  73.  
  74. The following files should be included with this file:
  75. * Install.txt  - Installation instructions.
  76. * Licence.txt  - User Licence.
  77. * ReadMe.txt   - This file
  78. * Versions.txt - Contains the Version History.
  79. * Bin\         - Here you'll find the compiled versions of the components for
  80.                  all the different platforms. The resource files (that contain
  81.                  the component bitmaps) can be found in the Glyph?? directories.
  82.                  Delphi 1 users should use the files in Glyph16, while other
  83.                  users should use the files in Glyph32.
  84. * Demos\       - Directory containing sample applications with source. You
  85.                  don't need to install the component to run the demos, just
  86.                  copy GIFImage.dcu and TimerEx.dcu to the Demo's directory.
  87. * Source\      - If you registered TGIFImage, you can get all the source here.
  88.  
  89.  
  90.  
  91. To install the components follow the steps set out in Install.txt.
  92.  
  93.  
  94.  
  95. {MWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMW}
  96. Part of the declaration of TGIFImage looks like this:
  97.   public
  98.     { Public declarations }
  99.     constructor Create(aOwner: TComponent); override;
  100.     destructor Destroy; override;
  101.     procedure Assign(Source: TPersistent); override;
  102.     procedure Clear;
  103.     function GetFrameInfo(const FrameIndex: Integer): TFrameInfo;
  104.  
  105.     function LoadFromFile(const GIFFileName: String): Boolean;
  106.     function LoadFromStream(Stream: TStream): Boolean;
  107.     function LoadInfoFromFile(const GIFFileName: String): Boolean;
  108.     function LoadInfoFromStream(Stream: TStream): Boolean;
  109.     function LoadFromResourceName(Instance: THandle; const ResName: String): Boolean;
  110.     function LoadFromResourceID(Instance: THandle; const ResID: Integer): Boolean;
  111.  
  112.     property Bitmap            : TBitmap       ;
  113.     property BitsPerPixel      : Integer       ;
  114.     property Data              : TMemoryStream ;
  115.     property Empty             : Boolean       ;
  116.     property ImageWidth        : Integer       ;
  117.     property ImageHeight       : Integer       ;
  118.     property IsAnimated        : Boolean       ;
  119.     property IsInterlaced      : Boolean       ;
  120.     property IsTransparent     : Boolean       ;
  121.     property MouseOnTransparent: Boolean       ;
  122.     property NumFrames         : Integer       ;
  123.     property NumIterations     : Integer       ;
  124.   published
  125.     { Published declarations }
  126.     { Inherited Properties...}
  127.  
  128.     { New Properties }
  129.     property Animate        : Boolean         ;
  130.     property AutoSize       : Boolean         ;
  131.     property Center         : Boolean         ;
  132.     property CurrentFrame   : Integer         ;
  133.     property DoubleBuffered : Boolean         ;
  134.     property FirstImageOnly : Boolean         ;
  135.     property Loop           : Boolean         ;
  136.     property Opaque         : Boolean         ;
  137.     property Speed          : Integer         ;
  138.     property Stretch        : Boolean         ;
  139.     property StretchRatio   : Boolean         ;
  140.     property Tile           : Boolean         ;
  141.     property Threaded       : Boolean         ;
  142.     property ThreadPriority : TThreadPriority ;
  143.     property Visible        : Boolean         ;
  144.     property Version        : TGIFVersion     ;
  145.     property OnChanging     : TNotifyEvent    ;
  146.     property OnChange       : TNotifyEvent    ;
  147.     property OnProgress     : TProgressEvent  ;
  148.     property OnWrapAnimation: TNotifyEvent    ;
  149.   end;
  150.  
  151.   function SaveToFile(const GIFFileName: String;
  152.                       var FramesArray: TSaveInfo): Boolean;
  153.  
  154.   function SaveToStream(Stream: TStream;
  155.                         var FramesArray: TSaveInfo): Boolean;
  156.  
  157.   function SaveToFileSingle(const GIFFileName: String;
  158.                             const aBitmap: TBitmap;
  159.                             const aInterlaced, aTransparent: Boolean;
  160.                             const aTransparentColor: TColor): Boolean;
  161.  
  162.   function SaveToStreamSingle(Stream: TStream;
  163.                               const aBitmap: TBitmap;
  164.                               const aInterlaced, aTransparent: Boolean;
  165.                               const aTransparentColor: TColor): Boolean;
  166.  
  167. var
  168.   LastWriteError: TGIFError;
  169.   OnWriteProgress: TProgressEvent;
  170. {MWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMWMW}
  171.  
  172.  
  173. TGIFImage has the following key properties:
  174.  
  175. * Animate : Boolean
  176.   Determines whether animated GIF's will be played or not.
  177.  
  178. * AutoSize : Boolean
  179.   Automatically sizes the component to the size of the GIF image if set.
  180.  
  181. * Bitmap : TBitmap (ReadOnly)
  182.   The GIF image itself. You can use this to save the image as a bitmap file using
  183.   Bitmap.SaveToFile. For animated GIF's the Bitmap property returns only the first frame.
  184.  
  185. * BitsPerPixel : Integer (ReadOnly)
  186.   The highest amount of bits per pixel for any image in the file.
  187.  
  188. * Center : Boolean
  189.   When the component is larger than the GIF image it will be centered within the component
  190.   boundaries if this property is set and neither the Stretch nor Tile properties are set.
  191.  
  192. * CurrentFrame : Integer
  193.   The frame currently displayed (1..NumFrames). You can also manually set this value to
  194.   display a particular frame of your choice.
  195.  
  196. * DoubleBuffered : Boolean
  197.   Determines whether the image should be painted to a temporary background bitmap and then
  198.   painted on the screen (True), or not (False). It's true by default and results in smooth,
  199.   flicker-free painting of animations. Setting it to False will speed up the painting
  200.   routines slightly.
  201.  
  202. * FirstImageOnly : Boolean
  203.   If True, only the first image will be decoded, even if there is more than one (animations).
  204.   This is useful if you're using it in eg. a browser where you don't want to see animation,
  205.   but only thumbnails.
  206.  
  207. * Empty : Boolean (ReadOnly)
  208.   This is True when no image is loaded.
  209.  
  210. * ImageWidth, ImageHeight : Integer (ReadOnly)
  211.   The dimensions of the loaded GIF.
  212.  
  213. * IsAnimated  : Boolean (ReadOnly)
  214.   If you want to know if the GIF is animated or not (Duh!)
  215.  
  216. * IsInterlaced  : Boolean (ReadOnly)
  217.   If you want to know if the GIF is interlaced or not.
  218.  
  219. * IsTransparent  : Boolean (ReadOnly)
  220.   Mmmm.... I wonder what this is for? Note that this is set when any 1 frame in the GIF is
  221.   transparent. So, even though some animations might not look like they have any transparent
  222.   areas, they do if this property is set. GIF animators use this technique to increase the
  223.   compression by replacing pixels which stay the same between frames with transparent ones.
  224.  
  225. * LastError: TGIFError
  226.   Where:
  227.   TGIFError = (geNone,
  228.                geInternal,
  229.                geFileFormat,
  230.                geTooManyColors,
  231.                geIndexOutOfBounds,
  232.                geWindows,
  233.                geFileNotFound,
  234.                geResourceNotFound
  235.                );
  236.   Note that no exceptions are raised within the component. The LastError property is simply
  237.   there for informational purposes if you receive a false result from one of the functions.
  238.  
  239. * Loop : Boolean
  240.   When set, animated GIF's will animate indefinitely. Otherwise they'll only run for the amount
  241.   of iterations specified in the file.
  242.  
  243. * Opaque : Boolean
  244.   If set to True, underlying areas not covered by the loaded image will be filled with
  245.   the Color property. It improves painting speed slightly for transparent images, and
  246.   some users requested this feature.
  247.  
  248. * MouseOnTransparent  : Boolean (ReadOnly)
  249.   This property is True when the pixel last passed over by the mouse was a transparent one. You
  250.   can use this property in the OnClick event handler for example to find out whether the user
  251.   clicked on a transparent area of the image.
  252.  
  253. * NumFrames: Integer (ReadOnly)
  254.   The number of images contained in the GIF. Equals 1 for standard GIF's, can be up to
  255.   MaximumGIFFrameCount (constant set at 256) for animated GIF's.
  256.  
  257. * NumIterations: Integer (ReadOnly)
  258.   The number of times an animated GIF will repeat. This value is ignored when Loop = True.
  259.  
  260. * Speed : Integer
  261.   The relative speed at which animations are played back. The value is as a percentage of the
  262.   GIF-specified speed and defaults to 100.
  263.  
  264. * Stretch : Boolean
  265.   When the component is larger than the GIF image it will be stretched to fit within the
  266.   component boundaries if this property is set. Stretch overrides the Tile property.
  267.  
  268. * StretchRatio : Boolean
  269.   Same as Stretch, except that the original image ratio (width:height) is preserved.
  270.   Stretch overrides the StretchRatio property.
  271.  
  272. * Threaded : Boolean
  273.   Selects whether the timing signals that control animation should use a seperate thread or not.
  274.   When this property is set to True, the animation will be smoother and will enable the main
  275.   application thread to continue with process-intensive tasks such as calculations without the
  276.   animation grinding to a halt.
  277.  
  278. * ThreadPriority : TThreadPriority
  279.   Select the system-wide priority given to the animation-signalling thread.
  280.  
  281. * Tile : Boolean
  282.   Well now, you all know what this is! Even animated GIF's can be tiled! This property works
  283.   well for displaying tileable backgrounds.
  284.  
  285. * Version : TGIFVersion
  286.   Where: TGIFVersion = (gvGIF87a, gvGIF89a);
  287.  
  288. * Visible : Boolean
  289.   The name says it all.
  290.  
  291.  
  292. The following methods are included:
  293.  
  294. * procedure Clear
  295.   Clears the loaded image and all internal buffers from memory.
  296.  
  297. * function GetFrameInfo(const FrameIndex: Integer): TFrameInfo
  298.   Enables you to gather information about a specific frame. Returns a TFrameInfo structure
  299.   which is defined as:
  300.  
  301.     TFrameInfo = Record
  302.       iiImage           : TBitmap;
  303.       iiLeft            : Integer;  {relative to whole image}
  304.       iiTop             : Integer;  {relative to whole image}
  305.       iiWidth           : Integer;
  306.       iiHeight          : Integer;
  307.       iiDelay           : Integer;  {in milliseconds, rounded to nearest 100}
  308.       iiInterlaced      : Boolean;
  309.       iiTransparent     : Boolean;
  310.       iiTransparentColor: TColor;
  311.       iiDisposalMethod  : TDisposalType;
  312.       iiComment         : String;
  313.     end;
  314.  
  315.   and TDisposalType is defined as:
  316.  
  317.     TDisposalType = (dtUndefined, dtDoNothing, dtToBackground, dtToPrevious);
  318.  
  319. * function LoadFromFile(const GIFFileName: String): Boolean
  320.   Similar to TBitmap.LoadFromFile and the FileName property, but it returns a result indicating
  321.   whether it loaded successfully or not.
  322.  
  323. * function LoadInfoFromFile(const GIFFileName: String): Boolean
  324.   Same as LoadFromFile, but doesn't decode or display the individual images. Useful for getting
  325.   a GIF's properties quickly. When using this function you can still refer to individual frames
  326.   and get their details by using the GetFrameInfo function, but all images will be returned as
  327.   nil instead of TBitmaps.
  328.  
  329. * function LoadInfoFromStream(Stream: TStream): Boolean
  330.   Same as LoadFromStream, but also only gathers GIF details.
  331.  
  332. * function LoadFromStream(Stream: TStream): Boolean
  333.   A lot of users asked for this one.
  334.  
  335. * function LoadFromResourceName(Instance: THandle; const ResName: String): Boolean
  336.   I included this to enable you to link a GIF file directly into your executable. Look at the
  337.   sample resource script included in the Demos\ResLoad directory.
  338.  
  339. * function LoadFromResourceID(Instance: THandle; const ResID: Integer): Boolean
  340.   Same as previous one, only uses Number instead of String for Resource ID.
  341.  
  342.  
  343. The following events are included:
  344.  
  345. * OnChanging: TNotifyEvent
  346.   This event is triggered just before the next frame is displayed.
  347.  
  348. * OnChange: TNotifyEvent
  349.   This event is triggered just after the next frame is displayed. During this call the
  350.   CurrentFrame property will be one more (or 1 if the animation looped) than in the preceding
  351.   OnChanging event.
  352.  
  353. * OnProgress: TProgressEvent
  354.   Enables the updating of a progress indicator while decoding the image,
  355.   where:
  356.     TProgressEvent = procedure(Sender: TObject;
  357.                                const BytesProcessed, BytesToProcess,
  358.                                PercentageProcessed: LongInt;
  359.                                var KeepOnProcessing: Boolean) of object;
  360.  
  361. * OnWrapAnimation: TNotifyEvent
  362.   This event is triggered when the animation has completed a single loop, ie. it will be called
  363.   NumIterations times if Loop = False.
  364.  
  365.  
  366.  
  367. The output routines are not part of the TGIFImage class (as it doesn't need to be) and
  368. comprises the following:
  369.  
  370. * function SaveToFile(const GIFFileName: String; const FramesArray: TSaveInfo): Boolean
  371.   Set up a TSaveInfo structure which is defined as:
  372.  
  373.     TSaveInfo = Record
  374.       siNumFrames          : Integer;
  375.       siFrames             : array[1..MaximumGIFFrameCount] of ^TFrameInfo;
  376.       siNumLoops           : Word;  {Number of times animation loop is run}
  377.       siUseGlobalColorTable: Boolean;
  378.     end;
  379.  
  380.   and then let rip! It can handle bitmaps of any color depth except Monochrome (1 bit per
  381.   pixel) because Win32's GetDIBits function does not seem to support it. One restriction though
  382.   is that each frame can not have more than 256 distinct colors, as the GIF format only
  383.   supports up to this amount. Maybe later on I'll include a Dithering algorithm, but nothing is
  384.   planned as yet... See the included Demo applications for examples on how to use this function.
  385.  
  386.   Most GIF animator applications write every image in an animation to the file with its own
  387.   color table (palette). If the total amount of colors used by all the images is 256 or less,
  388.   this results in a waste of space as only a single, global color table is needed. You can set
  389.   siUseGlobalColorTable to true to try and generate only a global color table. If this is not
  390.   possible, every image will be given a local color table. You can test the value of
  391.   siUseGlobalColorTable on return to see if a global color table was indeed generated. All
  392.   images are stored using the mimimum number of bits needed, thus resulting in greater
  393.   compression than simply assuming an 8-bit color depth.
  394.  
  395. * function SaveToStream(Stream: TStream; const FramesArray: TSaveInfo): Boolean
  396.   I suppose you can figure out how this works?
  397.  
  398. * function SaveToFileSingle(const GIFFileName: String;
  399.                             const aBitmap: TBitmap;
  400.                             const aInterlaced, aTransparent: Boolean;
  401.                             const aTransparentColor: TColor): Boolean;
  402.   A simplified, 1-line method to save a bitmap to GIF format.
  403.  
  404. * function SaveToStreamSingle(Stream: TStream;
  405.                               const aBitmap: TBitmap;
  406.                               const aInterlaced, aTransparent: Boolean;
  407.                               const aTransparentColor: TColor): Boolean;
  408.   As above, but for streams.
  409.  
  410. The following global variables can be used when output routines are used:
  411.  
  412. * LastWriteError : TGIFError;
  413.   Similar to the TGIFImage.LastError property, it contains the error code when an output
  414.   routine returns a False result.
  415.  
  416. * OnWriteProgress : TProgressEvent;
  417.   Similar to the TGIFImage.OnProgress property, it enables you to assign a progress-display
  418.   when using the output routines.
  419.  
  420.  
  421. New from version 2.5 is the ability to load an image while in the IDE by either double-clicking
  422. on the component or right-clicking and choosing the 'Load...' option on the popup menu which
  423. follows. Also on the popup menu is a 'Clear' function which disposes of the loaded image and
  424. a 'Refresh' option which just updates the display in case it got garbled.
  425.  
  426.  
  427. I hope this clears up all your questions. If not, drop me a line!
  428.  
  429. I love getting EMail so please tell me what you think of the component (it's my first). I've
  430. tested it on all the GIF's I could find and sorted out all the problems I encountered, but
  431. obviously there are many more out there...
  432.  
  433. Come by my site often to see if you have the latest release.
  434.  
  435. I wish to thank all those who mailed me their thoughts and ideas.
  436.  
  437. Hope you enjoy it and look forward to hearing from you soon!
  438.  
  439. Regards,
  440. Theodor
  441.  
  442. _____________________________________________________________________
  443. |                                                                   |
  444. | Theodor Kleynhans                                                 |
  445. |                                                                   |
  446. | theodor@sulako.com                                                |
  447. | http://www.sulako.com/                                            |
  448. |                                                                   |
  449. ---------------------------------------------------------------------
  450.