The Best of Mecomp Multimedia 2

home *** CD-ROM | disk | FTP | other *** search

/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / datatypes / gifanim_datatype / gifanim.datatype.doc < prev next >

Wrap

Text File | 1998-05-24 | 30.1 KB | 776 lines

TABLE OF CONTENTS gifanim.datatype/--datasheed-- gifanim.datatype/--input_format-- gifanim.datatype/ADTM_LOADFRAME gifanim.datatype/ADTM_UNLOADFRAME gifanim.datatype/DTM_WRITE gifanim.datatype/MAIN gifanim.datatype/OM_DISPOSE gifanim.datatype/OM_NEW gifanim.datatype/preferences gifanim.datatype/--datasheed-- gifanim.datatype/--datasheed-- NAME gifanim.datatype -- data type for GIF Animations SUPERCLASS animation.datatype DESCRIPTION The anim datatype, a sub-class of the animation.datatype, is used to load, play and encode (save) GIF animations. It supports GIF 87a and GIF 89a compressed animations. Using the prefs-file, any sound can be attached to the animation. METHODS OM_NEW -- Create a new animation object from a description file. The source may only be a file. Or an empty object can be created for encoding (which must be filled by the application before encoding). OM_DISPOSE -- Dispose instance and contents (frames, colormaps, sounds etc.), then pass msg to superclass OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the method will be executed like OM_SET downstairs. OM_SET -- Pass msg to superclass and call GM_RENDER if retval from superclass was != 0UL. DTM_WRITE -- Save object's contents in local (GIF Animation) or superclass (IFF ILBM) format. ADTM_LOADFRAME -- Fill in struct adtFrame with requested information from internal FrameNode list like bitmap, colormap and sample. If the bitmap information is not loaded yet, it will be loaded from disk. ADTM_UNLOADFRAME -- Free resources obtained by ADTM_UNLOADFRAME. All other methods are passed unchanged to superclass. ATTRIBUTES Following attributes are set by the object and are READ-ONLY for applications: DTA_ObjName - file name DTA_ObjAnnotation - set by extension blocks (gif 89a comment extention) DTA_TotalHoriz - same as ADTA_Width DTA_TotalVert - same as ADTA_Height ADTA_Width - set by GIF screen ADTA_Height - set by GIF screen ADTA_Depth - set by GIF screen ADTA_Frames - number of frames in animation ADTA_FramesPerSecond - fixed to 100 fps ADTA_ModeID - mode id flags ADTA_KeyFrame - Key frame of animation The following attributes are only set if a sample is attached using the prefs-file: ADTA_Sample - only set to notify the anmation.datatype instance that the object has sound data ADTA_SampleLength - size of sample data played within one timestamp ADTA_Period - sample period ADTA_Volume - volume as set by the prefs-file BUGS * The whole code looks like a big hack; sorry, but this datatype was put together within 2 hours... ...V1.2 only fixes some bugs and adds a few features. ...V1.3 fixed some things, adds some legal stuff and CyberGFX support - Does not support transparency yet (the encoder supports transparency througth a prefs-option). - Very slow playback. Reasons: - Multiple memory allocations, Seek's and Read's in one ADTM_LOADFRAME - Unbufferd loading - C2P conversion (fast, but not the fastest possible) - crap design - Slow gif decoder. Rewriting the beast in ASM maybe speed up things, but I don't know much about m68k assembler. Anybody out there who wants to do the job ? .... To get rid of this problem, the LOADALL switch is set for now. On >= mc68060/50MHz, the LOADALL switch in unneccesary, use NOLOADALL in this case... - Some anims get a trashed background, maybe due a bug in the GIF89a frame disposal support code. Any hint/example animation ? - This datatype was written for animation.datatype V41. Using this datatype with animation.datatype V40.6 does not work ! Not a bug, but... - In large videos, the frames at the end will be played slower than those at the beginning of the file. This is the result of the sequential search internally used (only serious with more than 25000 frames (mc6030/50mhz)). May or may not be fixed. - CyberGFX support is still under development. It seems that it works good, but... - CyberGFX C2P conversion (LUT8 -> RGB16/24) uses a very crap method througth WriteRGBPixel... - Some GIF89A_DISPOSE_RESTOREPREVIOUS and GIF89A_DISPOSE_NOP seems to be not handled correctly. But I need more example files to analyse this... TODO - Fixing the bugs above. - Write the "--input_format--"-Autodoc section. HISTORY V1.1 Released to the Waldspecht-BBS for testing. V1.2 - Found and fixed the longstanding bug that animation.datatype V40.7 didn't free some frames. Reason is that ADTM_LOADFRAME may be used like "realloc". Now alf_UserData is checked; any given frame will be freed (ADTM_UNLOADFRAME). Fixed. - Minor houskeeping changes; removed some unneccesary code. - Now uses buffered reading (FRead instead of Read and SetVBuf). Maybe this speeds up loading a little bit. - Fixed the bug in NOLOADALL loading mode (dynamic loading of frames from disk) that some "disposal" modes (previous image) didn't work properly under some conditions. Fixed. - Fixed the bug that animations with a static background were not correctly handled in LOADALL mode (I simply forgot to write the code...). Thanks to Francis Labrie (fb691875@er.uquam.ca) for reporting the bug. Fixed. - Fixed the bug that ADTM_LOADFRAME returns evertimes ERROR_NO_FREE_STORE on failure instead of returning the real cause. Also fixed the error handling code in ADTM_LOADFRAME. Fixed. - Implemented a delta mode for WPA8. If possible (e.g. if the current frame uses the previous one as it's background), only the changed areas are processed by the C2P code. - Now supports the GIF comment extension. The character set is converted automatically, chars > 128 are replaced by '_' except the german 'ä', 'ö', 'ü', 'Ä', 'Ö', 'Ü' and 'ß'. Multiple comment chunks are merged together. The comment will be stored in DTA_ObjAnnotation. - Cut some unneccesary VERBOSE output. V1.3 | Internal testing release to search for the mysterious memory loss | in conjunction with the 24BITCHUNKY option. - Added the notice that UniSys holds the LZW patents in the USA. - Removed BestModeIDA, because animation.datatype does the same thing. - Small code cleanup. Removed some of the debugging code and removed some parts of dead code. - Fixed the "maximum timestamp" (ADTA_Frames) calculation. the old way was very crap... Fixed. - Added some padding bytes in the decoder (instance data) part. Now the data are aligned, which should speed up the decoding. - Fixed possible problems when a GIF "Comment Extension" text is not '\0'-terminated. Now the load buffer is zero'ed for each new cycle. Fixed. - Added some VERBOSE about the "Plain Text Extension". The contents are now shown in the verbose output. - Fixed the bug that in the case that the first frame has no bitmap a bitmap with 0,0,0 dimensions would be allocated. (Did not occur, but...) Fixed. - Implemented a prefetch buffer for dynamic load mode (e.g. NOLOADALL); now all data needed for the frame are loaded with one Read statement, all following accesses are redirected to the filled buffer. Switched from FRead to Read again because we're now loading larger blocks. - Fixed the width padding problem, which caused an ugly border filled with rubbish in some anims. Fixed. - Now supports different disposal modes in one animation (each frame can have it's own disposal mode). - Now supports different transarent colors in one animation (each frame can have it's own transparent color). - Removed all references to ADTA_BitMapHeader. It's not required for this format. - Now saves the transparent color values from the previous colormap. - Fixed the bug that the datatypes creates everytimes a palette-per-frame instead of creating them only if neccesary. Fixed. - Now sets the GIF Screen background color to 0 if there is no global colormap. - Added CyberGFX-Support. Upon request, the datatype tries to create a 24-bit chunky bitmap if the 24BITCHUNKY prefs switch is set. WARNING: Does only work with animation.datatype V41 or higher (<= V41.2 had a small bug which has been fixed in V41.3). - Added CyberGFX bug workaround when BestCModeIDA fails when the dimensions given are too small (e.g. 32 * 50 returns INVALID_ID). Then 640 * 480 are set. Not very nice. - Added GIF Picture descriptor to replace any version with a wrong mask. V1.4 - Very much thanks to Frank Mariak (fmariak@chaosengine.ping.de) for finding the silly "too big palette"-bug in conjunction with the new chunkypixel output. V1.5 - Major code cleanup. BOOPSI class structures have been moved to classdata.h, class independed functions have been moved into misc.c, class preferences to prefs.c - Replaced the custom stackswapping code with my "standard" module "stackswap.c". - OM_DISPOSE now preserves Result2 (IoErr()). - Fixed the longstandig bug in ScanFrames that if an OS function failed, and IoErr results 0, havoc broke out. Fixed. - ADTA_SampleLength calculations were wrong. The value was got from the first frame. Now the value is set correctly to alf_SampleLength / (alf_Duration + 1) Fixed. - If a ADTM_LOADFRAME method gets a message from a previous ADTM_LOADFRAME call, the contents are freed now after the requested data have been loaded. This avoids the pathological case that if the same frame should be freed and returned the frame IS freed and then re-loaded. Now the free of the given frame is done after the loading of the requested frame which avoids this inefficienty. Fixed. - Switched truecolor output down to 16 bit (565-bits-per-gun) to save some mem... - Added 16BITCHUNKY, NO16BITCHUNKY, TRUECOLOR and NOTRUECOLOR options. - Fixed ModeID handling. The previous behaviour was that a 0 mode id causes the datatype to select it's own mode id. But 0 means LORES. Now the default is -1 (which means INVALID_ID), which causes the datatype to do it's own calculations. Fixed. V1.6 internal version for testing V2.1 - Implemeted the GIF animation encoder part. The encoder writes GIF89a animation streams out. - Fixed a mask bug in the suppied "GIF" descriptor; a byte after the "GIF" signature was set to match, Fixed. - gifanim.datatype now requires at least animation.datatype V41 as base class. (mainly to get rid of the V40 workround code which tried to get class working with animation.datatype V40). - Updated and cleaned-up the autodoc a little bit. V2.2 - Minor code cleanup - Removed REPEAT and NOREPEAT options/feature because this hack-like "feature" seems to be incompatible to GMultiView's repeat option. Problem fixed. - Added encoder prefs options to set GIF interlace mode, transparent and background pens. See "gifanim.datatype.doc" section "preferences" for details. Currently untested... - Major speedup in the encoder part (~ three times faster). a) The encoder now writes any incoming bitmap in an chunkypixel array and operates on it instead of doing ReadPixel for each pixel. b) Minor other changes in the encoder section... - The decoder now treats 0x00-chars in the chunk id position as padding bytes and does not prompt any sytax error any more. Now the "slidbar.gif" created by "GifBuilder 0.2" works... - Introduced the option STRICTSYNTAX which prints additionally syntax errors (like the 0x00 padding bytes above...). - Added Installation script "Install DataType". It would be very nice if someone has the time to write a 1:1 CBM Installer version of it... V2.3 - Fixed a couple of holes in the descriptor code which may caused endless loops or - more worse - crashes in the past. Thanks to Guillaume Ubbelohde (950947@mercure.umh.ac.be) for reporting the bug. - The descriptor now checks if the given gif stream is a multi-picture gif stream or not, nothing else ! Syntax checking/version checking etc. is NOT done, this is the job of the decoder (e.g. the class library). - The error checking in the decoder has been improved a little bit. Still not perfect, but... - The decoder now explains most errors in a console window. - Implemented a NOVERBOSE option (as requested by many people), which turns all error messages OFF. Be carefull with this option !!! - Minor code changes and optimisations. NOTES This datatype first scans the whole animation to get index information (if the LOADALL switch was set in the prefs-file, the entire animation will be loaded), colormaps will be loaded immediately. SEE ALSO animation.datatype, anim.datatype, mpegsystem.datatype, mpegvideo.datatype, picmovie.datatype, cdxl.datatype, avi.datatype, quicktime.datatype, moviesetter.datatype, film.datatype, directory.datatype, markabletextdtclass gifanim.datatype/--input_format-- gifanim.datatype/--input_format-- NAME GIF ANIM -- GIF Animation format DESCRIPTION <Not written yet, sorry> SEE ALSO gif.doc, gif89a.doc, compress.gif gifanim.datatype/ADTM_LOADFRAME gifanim.datatype/ADTM_LOADFRAME NAME ADTM_LOADFRAME -- Load frame FUNCTION The ADTM_LOADFRAME method is used to obtain the bitmap and timing data of the animation. The given timestamp will be used to find a matching timestamp in the internal FrameNode list. If it was found, the corresponding timing, bitmap and colormap data are stored into the struct adtFrame. If the bitmap wasn't loaded, this method attempts to load it from disk. RESULT the bitmap ptr if a bitmap was found, 0 (and result2 with the reason). gifanim.datatype/ADTM_UNLOADFRAME gifanim.datatype/ADTM_UNLOADFRAME NAME ADTM_UNLOADFRAME -- Unload frame contents FUNCTION The ADTM_UNLOADFRAME method is used to release the contents of a animation frame. This method frees the bitmap data found in adtFrame. RESULT Returns always 0UL. gifanim.datatype/DTM_WRITE gifanim.datatype/DTM_WRITE NAME DTM_WRITE -- Save data FUNCTION This method saves the object's contents to disk. If dtw_Mode is DTWM_IFF, the method is passed unchanged to the superclass, animation.datatype, which writes a single IFF ILBM picture. If dtw_mode is DTWM_RAW, the object saved an GIF Animation stream to the filehandle given, starting with the current frame until the end is reached. The sequence saved can be controlled by the ADTA_Frame, ADTA_Frames and ADTA_FrameIncrement attributes (see TAGS section below). TAGS When writing the local ("raw") format, GIF Animation, the following attributes are recognized: ADTA_Frame (ULONG) - start frame, saving starts here. Defaults to the current frame displayed. ADTA_Frames (ULONG) - the number of frames to be saved, Defaults to (max_num_of_frames - curr_frame). ADTA_FrameIncrement (ULONG) - frame increment when saving. Defaults to 1, which means: "jump to next frame". NOTE - Any sound attached to the animation will NOT be saved. - A CTRL-D signal to the writing process aborts the save. RESULT Returns 0 for failure (IoErr() returns result2), non-zero for success. gifanim.datatype/MAIN gifanim.datatype/MAIN INTRODUCTION Datatypes class for GIF animations. Based on "giftopnm" by David Koblas, "ppmtogif" by Marcel Wijkstra <wijkstra@fwi.uva.nl> and David Rowley <mgardi@watdscu.waterloo.edu> and the CBM datatypes example source/ documents written by David Junod. LEGAL * Note that this implementation uses LZW, which is PATENTED by UniSys in the U.S.A. Therefore, this application must not be used inside the United States of America except for research purposes. - Compuserves banner: "The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated." - "giftopnm" legal info: +-------------------------------------------------------------------+ | Copyright 1990, 1991, 1993, David Koblas. (koblas@netcom.com) | | Permission to use, copy, modify, and distribute this software | | and its documentation for any purpose and without fee is hereby | | granted, provided that the above copyright notice appear in all | | copies and that both that copyright notice and this permission | | notice appear in supporting documentation. This software is | | provided "as is" without express or implied warranty. | +-------------------------------------------------------------------+ REQUIREMENTS - You need at least Kick/WB 3.0. | Many people wrote me that they cannot find an | "animation.datatype" class. | Only the 3.1 release contains it. (Subclasses of) | animation.datatype can run under 3.0. - "datatypes/animation.datatype", >= V41 "animation.datatype V41" requires itself some libraries/boopsi classes: - "realtime.library", >= V39 - for timing - "gadgets/tapedeck.gadget" (any version) - for the controls If you want to attach samples, you need "sound.datatype" >= V39 and your prefereed subclass (8svx.datatype for IFF 8SVX samples etc.). USAGE If the datatypes descriptor file was activated, any attempt to load a GIF anim stream using GMultiView, MultiView, AmigaGuide or SwitchWindow will load and play the animation. If the source was a file, gifanim.datatype loads frames dynamically from disk. If you want to save the current animation in gifanim.datatype's local format, use MultiView's "Project/Save As..." menu (or GMultiView's "Project/Save As Raw..."). gifanim.datatype saves the current animation, starting with the current frame as GIF animation. If you want to attach samples to the animation, you must edit the prefs file (ENV:Classes/DataTypes/gifanim.prefs) and add the following line: VERBOSE SAMPLE="ram:have_a_nice_day.8svx" Which loads and attaches the sample "ram:have_a_nice_day.8svx" to the animation. See gifanim.datatype.doc/preferences for a complete description of the prefs file. INSTALLATION After unpacking this archive: Because this version does not include an Installer script, you have to do the installation manually through the shell: - Unpack this archive and copy the "gifanim.datatype" to SYS:Classes/DataTypes/: Copy CLONE FROM "gifanim.datatype" TO "SYS:Classes/DataTypes/gifanim.datatype" - Then copy the datatypes descriptor into the DEVS:DataTypes directory. If the descriptor already exists, you should not replace it, otherwise you may loose "toolnodes" and other settings stored in the existing descriptor. Copy CLONE FROM "GIFANIM(%|.info)" TO DEVS:Datatypes/ SOURCE Source is included as an example how to write an animation.datatype subclass which deals with things chunky bitmaps deltas and an encoder... AUTHOR If you want to blame me, report any bugs, or wants a new version send your letter to: Roland Mainz Hohenstaufenstraße 8 52388 Nörvenich GERMANY Phone: (+49)(0)2426/901568 Fax: (+49)(0)2426/901569 EMAIL is also available (if you want to send me attachments larger than 1MB (up to 5MB, more with my permission): GISBURN@w-specht.rhein-ruhr.de Up to July 1998 I'm reachable using this email address, too: Reinhold.A.Mainz@KBV.DE | Please put your name and address in your mails ! | German mailers should add their phone numbers. | See BUGS section above when submitting bug reports. Sorry, but I can only look once a week for mails. If you don't hear something from me within three weeks, please send your mail again (but watch about new releases) (problems with this email port are caused by reconfigurations, hackers, network problems etc.). The entire "gifanim.datatype" package may be noncommercially redistributed, provided that the package is always distributed in it's complete form (including it's documentation). A small copy fee for media costs is okay but any kind of commercial distribution is strictly forbidden without my permission ! Comments and suggestions how to improve this program are generally appreciated! Thanks to David Junod, who wrote the animation.datatype and lots of the datatypes example code, David Koblas for his "giftopnm" and other people for their compression formats, Peter McGavin for his C2P function, Matt Dillon for his DICE, Olaf 'Olsen' Barthel for his help, ideas and some text clips from his documentations. gifanim.datatype/OM_DISPOSE gifanim.datatype/OM_DISPOSE NAME OM_DISPOSE -- Delete a gifanim.datatype object. FUNCTION The OM_DISPOSE method is used to delete an instance of the gifanim.datatype class. This method is passed to the superclass when it has completed. This method frees all frame nodes and their contents (bitmaps, colormaps, samples etc.) RESULT The object is deleted. 0UL is returned. gifanim.datatype/OM_NEW gifanim.datatype/OM_NEW NAME OM_NEW -- Create a gifanim.datatype object. FUNCTION The OM_NEW method is used to create an instance of the gifanim.datatype class. This method is passed to the superclass first. After this, gifanim.datatype parses the prefs file and makes a scan through the data to get index information. Frame bitmaps are loaded if the input stream isn't seekable, colormaps and the first frame are loaded immediately. If a sample was set in the prefs, it will be loaded and attached to the animation. ATTRIBUTES The following attributes can be specified at creation time. DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle attribute. Only DTST_FILE and DTST_RAM are supported. If any other type was set in a given DTA_SourceType, OM_NEW will be rejected. Defaults to DTST_FILE. DTA_Handle -- For DTST_FILE, a BPTR filehandle is expected. This handle will be created by datatypesclass depeding on the DTF_#? flag, which is DTF_BINARY here. DTST_FILE, datatypesclass creates a file handle from the given DTA_Name and DTA_Handle (a BPTR returned by Lock). A DTST_RAM (create empty object) source type requires a NULL handle. RESULT If the object was created a pointer to the object is returned, otherwise NULL is returned. gifanim.datatype/preferences gifanim.datatype/preferences NAME preferences DESCRIPTION The "ENV:Classes/DataTypes/gifanim.prefs" file contains global settings for the datatype. The preferences file is an ASCII file containing one line where the preferences can be set. It can be superset by a local variable with the same name. Each line can contain settings, special settings for some projects can be set using the MATCHPROJECT option. Lines beginning with a '#' or ';' chars are treated as comments. Lines are limitted to 256 chars. TEMPLATE MATCHPROJECT/K,VERBOSE/S,NOVERBOSE/S,STRICTSYNTAX/S,NOSTRICTSYNTAX/S, MODEID/K/N,16BITCHUNKY=24BITCHUNKY=TRUECOLOR/S, NO16BITCHUNKY=NO24BITCHUNKY=NOTRUECOLOR/S,FPS/K/N, SAMPLE/K,SAMPLESPERFRAME=SPF/K/N,VOLUME/K/N,LOADALL/S, NOLOADALL/S,ENC_INTERLACE/S,ENC_NO_INTERLACE/S, ENC_BACKGROUNDPEN=ENC_BG/K/N,ENC_TRANSPARENTPEN=ENC_TRANSPARENT/K/N MATCHPROJECT -- The settings in this line belongs only to this project(s), e.g. if the case-insensitive pattern does not match, this line is ignored. The maximum length of the pattern is 128 chars. Defaults to #?, which matches any project. VERBOSE -- Print information about the animation. Currently the frame numbers and the used compression are printed, after all number of scanned/loaded frames, set FPS rate, dimensions (width/ height/depth), sample information etc. NOVERBOSE -- Turns verbose output and error messages OFF. Be carefull, you won't see any error messages any more !!! STRICTSYNTAX -- Prompt syntax errors in the gif streams. NOSTRICTSYNTAX -- Turns STRICTSYNTAX off MODEID -- Select screen mode id of datatype (will be stored in ADTA_ModeID). Note that the DOS ReadArgs function used for parsing fetches a SIGNED long. The bit 31 will be represented by minus '-'. (example: "MODEID=266240" sets the mode to the A2024 screen mode id) Defaults to -1, which means: Use the best screenmode available for the given width, height and depth. 16BITCHUNKY 24BITCHUNKY TRUECOLOR -- Create 24 bit chunky bitmaps, if possible. Note that the 16BITCHUNKY and the 24BITCHUNKY options will be seperated in the future. The TRUECOLOR option selects the best truecolor depth in this case... NO16BITCHUNKY NO24BITCHUNKY NOTRUECOLOR -- Turns 24BITCHUNKY option off. (Default) Note that the 16BITCHUNKY and the 24BITCHUNKY options will be seperated in the future. The TRUECOLOR option selects the best truecolor depth in this case... FPS -- Frames Per Second A value of 0 here means: Use default FPS. SAMPLE -- Attach the given sample to the animation. The sample will be loaded using datatypes (GID_SOUND). Only one sample can be attached to one animation stream, any following attempt to attach a sample will be ignored. SAMPLESPERFRAME -- Set samples per frame rate for sound. This overrides the own internal calculations to get rid of rounding errors. VOLUME -- Volume of the sound when playing. Defaults to 64, which is the maximum. A value greater than 64 will be set to 64. LOADALL -- Load all frames into memory. NOLOADALL -- Turns off the LOADALL flag, which may be set in a prefs- line before. This switch is set per default, and can be turned off by the LOADALL option, later it can be turned on again by this option. Encoder related options: ENC_INTERLACE - create interlaced gif animation ENC_NO_INTERLACE - create non-interlaced gif animation (set per default). ENC_BACKGROUNDPEN ENC_BG - background pen number Defaults to 0 (e.g. default bg pen) ENC_TRANSPARENTPEN ENC_TRANSPARENT - transparent pen number Defaults to -1 (means: no transparent pen). NOTE - An invalid prefs file line will be ignored and forces the VERBOSE output. BUGS - Low memory may cause that the prefs file won't be parsed. - Lines are limitted to 256 chars - An invalid prefs file line will be ignored. - The sample path length is limitted to 200 chars. A larger value may crash the machine if an error occurs.