home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #4 / amigamamagazinepolishissue1998.iso / datatypes / gifanimdtc201.lha / gifanim_datatype / gifanim.datatype.doc < prev    next >
Text File  |  1998-03-23  |  28KB  |  695 lines
  1. TABLE OF CONTENTS
  2.  
  3. gifanim.datatype/--datasheed--
  4. gifanim.datatype/--input_format--
  5. gifanim.datatype/ADTM_LOADFRAME
  6. gifanim.datatype/ADTM_UNLOADFRAME
  7. gifanim.datatype/DTM_WRITE
  8. gifanim.datatype/MAIN
  9. gifanim.datatype/OM_DISPOSE
  10. gifanim.datatype/OM_NEW
  11. gifanim.datatype/preferences
  12. gifanim.datatype/--datasheed--                 gifanim.datatype/--datasheed--
  13.  
  14.    NAME
  15.        gifanim.datatype -- data type for GIF Animations
  16.  
  17.    SUPERCLASS
  18.        animation.datatype
  19.  
  20.    DESCRIPTION
  21.        The anim datatype, a sub-class of the animation.datatype, is used to
  22.        load, play and encode (save) GIF animations.
  23.        It supports GIF 87a and GIF 89a compressed animations.
  24.        Using the prefs-file, any sound can be attached to the animation.
  25.  
  26.    METHODS
  27.        OM_NEW -- Create a new animation object from a description file. The
  28.            source may only be a file. Or an empty object can be created for 
  29.            encoding (which must be filled by the application before 
  30.            encoding).
  31.  
  32.        OM_DISPOSE -- Dispose instance and contents (frames, colormaps, sounds
  33.            etc.), then pass msg to superclass
  34.  
  35.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  36.            method will be executed like OM_SET downstairs.
  37.  
  38.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  39.            superclass was != 0UL.
  40.  
  41.        DTM_WRITE -- Save object's contents in local (GIF Animation) or
  42.            superclass (IFF ILBM) format.
  43.  
  44.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  45.            from internal FrameNode list like bitmap, colormap and sample. If
  46.            the bitmap information is not loaded yet, it will be loaded from
  47.            disk.
  48.  
  49.        ADTM_UNLOADFRAME -- Free resources obtained by ADTM_UNLOADFRAME.
  50.  
  51.        All other methods are passed unchanged to superclass.
  52.  
  53.    ATTRIBUTES
  54.        Following attributes are set by the object and are READ-ONLY for
  55.        applications:
  56.        DTA_ObjName             - file name
  57.        DTA_ObjAnnotation       - set by extension blocks (gif 89a comment
  58.                                  extention)
  59.        DTA_TotalHoriz          - same as ADTA_Width
  60.        DTA_TotalVert           - same as ADTA_Height
  61.        ADTA_Width              - set by GIF screen
  62.        ADTA_Height             - set by GIF screen
  63.        ADTA_Depth              - set by GIF screen
  64.        ADTA_Frames             - number of frames in animation
  65.        ADTA_FramesPerSecond    - fixed to 100 fps
  66.        ADTA_ModeID             - mode id flags
  67.        ADTA_KeyFrame           - Key frame of animation
  68.  
  69.        The following attributes are only set if a sample is attached using 
  70.        the prefs-file:
  71.        ADTA_Sample             - only set to notify the anmation.datatype
  72.                                  instance that the object has sound data
  73.        ADTA_SampleLength       - size of sample data played within one 
  74.                                  timestamp
  75.        ADTA_Period             - sample period
  76.        ADTA_Volume             - volume as set by the prefs-file
  77.  
  78.    BUGS
  79.        * The whole code looks like a big hack; sorry, but this datatype was
  80.          put together within 2 hours...
  81.          ...V1.2 only fixes some bugs and adds a few features.
  82.          ...V1.3 fixed some things, adds some legal stuff and CyberGFX
  83.             support
  84.  
  85.        - Does not support transparency yet.
  86.  
  87.        - Very slow playback.
  88.          Reasons:
  89.          - Multiple memory allocations, Seek's and Read's in one
  90.            ADTM_LOADFRAME
  91.          - Unbufferd loading
  92.          - C2P conversion (fast, but not the fastest possible)
  93.          - crap design
  94.          - Slow gif decoder. Rewriting the beast in ASM maybe speed up
  95.            things, but I don't know much about m68k assember.
  96.            Anybody out there who wants to do the job ?
  97.          ....
  98.  
  99.          To get rid of this problem, the LOADALL switch is set for now.
  100.          On >= mc68040/40MHz, the LOADALL switch in unneccesary, use
  101.          NOLOADALL in this case...
  102.  
  103.        - Some anims get a trashed background, maybe due a bug in the GIF89a
  104.          frame disposal support code.
  105.  
  106.        - This datatype was written for animation.datatype V41. Using this
  107.          datatype with animation.datatype V40.6 does not work !
  108.  
  109.        - In large videos, the frames at the end will be played slower than
  110.          those at the beginning of the file. This is the result of the
  111.          sequential search internally used (only serious with more than 25000
  112.          frames (mc6030/50mhz)).
  113.          May or may not be fixed.
  114.  
  115.        - CyberGFX support is still under development. It seems that it works
  116.          good, but...
  117.  
  118.        - CyberGFX C2C conversion (LUT8 -> RGB16/24) uses a very crap method
  119.          througth WriteRGBPixel...
  120.  
  121.    TODO
  122.        - Fixing the bugs above.
  123.  
  124.        - Write the "--input_format--"-Autodoc section.
  125.  
  126.    HISTORY
  127.        V1.1
  128.          Released to the Waldspecht-BBS for testing.
  129.  
  130.        V1.2
  131.          - Found and fixed the longstanding bug that animation.datatype
  132.            V40.7 didn't free some frames. Reason is that ADTM_LOADFRAME
  133.            may be used like "realloc". Now alf_UserData is checked;
  134.            any given frame will be freed (ADTM_UNLOADFRAME).
  135.            Fixed.
  136.  
  137.          - Minor houskeeping changes; removed some unneccesary code.
  138.  
  139.          - Now uses buffered reading (FRead instead of Read and SetVBuf).
  140.            Maybe this speeds up loading a little bit.
  141.  
  142.          - Fixed the bug in NOLOADALL loading mode (dynamic loading of
  143.            frames from disk) that some "disposal" modes (previous image)
  144.            didn't work properly under some conditions.
  145.            Fixed.
  146.  
  147.          - Fixed the bug that animations with a static background were
  148.            not correctly handled in LOADALL mode (I simply forgot
  149.            to write the code...).
  150.            Thanks to Francis Labrie (fb691875@er.uquam.ca) for reporting
  151.            the bug.
  152.            Fixed.
  153.  
  154.          - Fixed the bug that ADTM_LOADFRAME returns evertimes
  155.            ERROR_NO_FREE_STORE on failure instead of returning the real
  156.            cause.
  157.            Also fixed the error handling code in ADTM_LOADFRAME.
  158.            Fixed.
  159.  
  160.          - Implemented a delta mode for WPA8. If possible (e.g. if the
  161.            current frame uses the previous one as it's background), only
  162.            the changed areas are processed by the C2P code.
  163.  
  164.          - Now supports the GIF comment extension. The character set is
  165.            converted automatically, chars > 128 are replaced by '_'
  166.            except the german 'ä', 'ö', 'ü', 'Ä', 'Ö', 'Ü' and 'ß'.
  167.            Multiple comment chunks are merged together.
  168.            The comment will be stored in DTA_ObjAnnotation.
  169.  
  170.          - Cut some unneccesary VERBOSE output.
  171.  
  172.        V1.3
  173.          | Internal testing release to search for the mysterious memory loss
  174.          | in conjunction with the 24BITCHUNKY option.
  175.  
  176.          - Added the notice that UniSys holds the LZW patents in the USA.
  177.  
  178.          - Removed BestModeIDA, because animation.datatype does the same
  179.            thing.
  180.  
  181.          - Small code cleanup.
  182.            Removed some of the debugging code and removed some parts of
  183.            dead code.
  184.  
  185.          - Fixed the "maximum timestamp" (ADTA_Frames) calculation.
  186.            the old way was very crap...
  187.            Fixed.
  188.  
  189.          - Added some padding bytes in the decoder (instance data) part.
  190.            Now the data are aligned, which should speed up the decoding.
  191.  
  192.          - Fixed possible problems when a GIF "Comment Extension" text is
  193.            not '\0'-terminated. Now the load buffer is zero'ed for each new
  194.            cycle.
  195.            Fixed.
  196.  
  197.          - Added some VERBOSE about the "Plain Text Extension". The contents
  198.            are now shown in the verbose output.
  199.  
  200.          - Fixed the bug that in the case that the first frame has no bitmap
  201.            a bitmap with 0,0,0 dimensions would be allocated.
  202.            (Did not occur, but...)
  203.            Fixed.
  204.  
  205.          - Implemented a prefetch buffer for dynamic load mode (e.g.
  206.            NOLOADALL); now all data needed for the frame are loaded with one
  207.            Read statement, all following accesses are redirected to the
  208.            filled buffer.
  209.            Switched from FRead to Read again because we're now loading
  210.            larger blocks.
  211.  
  212.          - Fixed the width padding problem, which caused an ugly border
  213.            filled with rubbish in some anims.
  214.            Fixed.
  215.  
  216.          - Now supports different disposal modes in one animation (each
  217.            frame can have it's own disposal mode).
  218.  
  219.          - Now supports different transarent colors in one animation (each
  220.            frame can have it's own transparent color).
  221.  
  222.          - Removed all references to ADTA_BitMapHeader. It's not required
  223.            for this format.
  224.  
  225.          - Now saves the transparent color values from the previous colormap.
  226.  
  227.          - Fixed the bug that the datatypes creates everytimes a
  228.            palette-per-frame instead of creating them only if neccesary.
  229.            Fixed.
  230.  
  231.          - Now sets the GIF Screen background color to 0 if there is no
  232.            global colormap.
  233.  
  234.          - Added CyberGFX-Support. Upon request, the datatype tries to create
  235.            a 24-bit chunky bitmap if the 24BITCHUNKY prefs switch is set.
  236.            WARNING: Does only work with animation.datatype V41 or higher
  237.            (<= V41.2 had a small bug which has been fixed in V41.3).
  238.  
  239.          - Added CyberGFX bug workaround when BestCModeIDA fails when the
  240.            dimensions given are too small (e.g. 32 * 50 returns INVALID_ID).
  241.            Then 640 * 480 are set.
  242.            Not very nice.
  243.  
  244.          - Added GIF Picture descriptor to replace any version with a wrong
  245.            mask.
  246.  
  247.        V1.4
  248.          - Very much thanks to Frank Mariak (fmariak@chaosengine.ping.de)
  249.            for finding the silly "too big palette"-bug in conjunction
  250.            with the new chunkypixel output.
  251.  
  252.        V1.5
  253.          - Major code cleanup. BOOPSI class structures have been moved
  254.            to classdata.h, class independed functions have been moved
  255.            into misc.c, class preferences to prefs.c
  256.  
  257.          - Replaced the custom stackswapping code with my "standard"
  258.            module "stackswap.c".
  259.  
  260.          - OM_DISPOSE now preserves Result2 (IoErr()).
  261.  
  262.          - Fixed the longstandig bug in ScanFrames that if an OS function
  263.            failed, and IoErr results 0, havoc broke out.
  264.            Fixed.
  265.  
  266.          - ADTA_SampleLength calculations were wrong. The value was got
  267.            from the first frame. Now the value is set correctly to
  268.            alf_SampleLength / (alf_Duration + 1)
  269.            Fixed.
  270.  
  271.          - If a ADTM_LOADFRAME method gets a message from a previous
  272.            ADTM_LOADFRAME call, the contents are freed now after
  273.            the requested data have been loaded. This avoids the
  274.            pathological case that if the same frame should be freed and
  275.            returned the frame IS freed and then re-loaded.
  276.            Now the free of the given frame is done after the loading
  277.            of the requested frame which avoids this inefficienty.
  278.            Fixed.
  279.  
  280.          - Switched truecolor output down to 16 bit (565-bits-per-gun)
  281.            to save some mem...
  282.  
  283.          - Added 16BITCHUNKY, NO16BITCHUNKY, TRUECOLOR and NOTRUECOLOR
  284.            options.
  285.  
  286.          - Fixed ModeID handling. The previous behaviour was that
  287.            a 0 mode id causes the datatype to select it's own mode id.
  288.            But 0 means LORES. Now the default is -1 (which means
  289.            INVALID_ID), which causes the datatype to do it's own
  290.            calculations.
  291.            Fixed.
  292.  
  293.        V2.1
  294.          - Implemeted the GIF animation encoder part.
  295.            The encoder writes GIF89a animation streams out.
  296.  
  297.          - Fixed a mask bug in the suppied "GIF" descriptor;
  298.            a byte after the "GIF" signature was set to match,
  299.            Fixed.
  300.  
  301.          - gifanim.datatype now requires at least animation.datatype V41
  302.            as base class.
  303.            (mainly to get rid of the V40 workround code which tried to
  304.            get class working with animation.datatype V40).
  305.  
  306.          - Updated and cleaned-up the autodoc a little bit.
  307.  
  308.    NOTES
  309.        This datatype first scans the whole animation to get index
  310.        information (if the LOADALL switch was set in the prefs-file,
  311.        the entire animation will be loaded), colormaps will be loaded
  312.        immediately.
  313.  
  314.    SEE ALSO
  315.        animation.datatype,
  316.        anim.datatype,
  317.        mpegsystem.datatype, mpegvideo.datatype,
  318.        picmovie.datatype,
  319.        cdxl.datatype, avi.datatype, quicktime.datatype,
  320.        moviesetter.datatype,
  321.        film.datatype,
  322.        directory.datatype,
  323.        markabletextdtclass
  324.  
  325. gifanim.datatype/--input_format--           gifanim.datatype/--input_format--
  326.  
  327.     NAME
  328.         GIF ANIM -- GIF Animation format
  329.  
  330.     DESCRIPTION
  331.         <Not written yet, sorry>
  332.  
  333.     SEE ALSO
  334.         gif.doc, gif89a.doc, compress.gif
  335.  
  336. gifanim.datatype/ADTM_LOADFRAME               gifanim.datatype/ADTM_LOADFRAME
  337.  
  338.     NAME
  339.         ADTM_LOADFRAME -- Load frame
  340.  
  341.     FUNCTION
  342.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  343.         data of the animation.
  344.         The given timestamp will be used to find a matching timestamp
  345.         in the internal FrameNode list. If it was found, the corresponding
  346.         timing, bitmap and colormap data are stored into the struct
  347.         adtFrame. If the bitmap wasn't loaded, this method attempts to
  348.         load it from disk.
  349.  
  350.     RESULT
  351.         the bitmap ptr if a bitmap was found,
  352.         0 (and result2 with the reason).
  353.  
  354. gifanim.datatype/ADTM_UNLOADFRAME           gifanim.datatype/ADTM_UNLOADFRAME
  355.  
  356.     NAME
  357.         ADTM_UNLOADFRAME -- Unload frame contents
  358.  
  359.     FUNCTION
  360.         The ADTM_UNLOADFRAME method is used to release the contents of a
  361.         animation frame.
  362.  
  363.         This method frees the bitmap data found in adtFrame.
  364.  
  365.     RESULT
  366.         Returns always 0UL.
  367.  
  368. gifanim.datatype/DTM_WRITE                         gifanim.datatype/DTM_WRITE
  369.  
  370.     NAME
  371.         DTM_WRITE -- Save data
  372.  
  373.     FUNCTION
  374.         This method saves the object's contents to disk.
  375.  
  376.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  377.         superclass, animation.datatype, which writes a single IFF ILBM
  378.         picture.
  379.  
  380.         If dtw_mode is DTWM_RAW, the object saved an GIF Animation stream 
  381.         to the filehandle given, starting with the current frame until
  382.         the end is reached.
  383.         The sequence saved can be controlled by the ADTA_Frame, ADTA_Frames
  384.         and ADTA_FrameIncrement attributes (see TAGS section below).
  385.  
  386.     TAGS
  387.         When writing the local ("raw") format, GIF Animation, the following
  388.         attributes are recognized:
  389.  
  390.         ADTA_Frame (ULONG) - start frame, saving starts here.
  391.             Defaults to the current frame displayed.
  392.  
  393.         ADTA_Frames (ULONG) - the number of frames to be saved,
  394.             Defaults to (max_num_of_frames - curr_frame).
  395.  
  396.         ADTA_FrameIncrement (ULONG) - frame increment when saving.
  397.             Defaults to 1, which means: "jump to next frame".
  398.  
  399.     NOTE
  400.         - Any sound attached to the animation will NOT be saved.
  401.  
  402.         - A CTRL-D signal to the writing process aborts the save.
  403.  
  404.     RESULT
  405.         Returns 0 for failure (IoErr() returns result2), non-zero
  406.         for success.
  407.  
  408. gifanim.datatype/MAIN                                   gifanim.datatype/MAIN
  409.  
  410.     INTRODUCTION
  411.         Datatypes class for GIF animations. Based on "giftopnm" by David
  412.         Koblas, "ppmtogif" by Marcel Wijkstra <wijkstra@fwi.uva.nl> and
  413.         David Rowley <mgardi@watdscu.waterloo.edu> and the CBM datatypes 
  414.         example source/ documents written by David Junod.
  415.  
  416.     LEGAL
  417.       * Note that this implementation uses LZW, which is PATENTED by UniSys
  418.         in the U.S.A.
  419.  
  420.         Therefore, this application must not be used inside the United
  421.         States of America except for research purposes.
  422.  
  423.       - Compuserves banner:
  424.  
  425.       "The Graphics Interchange Format(c) is the Copyright property of
  426.       CompuServe Incorporated. GIF(sm) is a Service Mark property of
  427.       CompuServe Incorporated."
  428.  
  429.       - "giftopnm" legal info:
  430.       +-------------------------------------------------------------------+
  431.       | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    |
  432.       |   Permission to use, copy, modify, and distribute this software   |
  433.       |   and its documentation for any purpose and without fee is hereby |
  434.       |   granted, provided that the above copyright notice appear in all |
  435.       |   copies and that both that copyright notice and this permission  |
  436.       |   notice appear in supporting documentation.  This software is    |
  437.       |   provided "as is" without express or implied warranty.           |
  438.       +-------------------------------------------------------------------+
  439.  
  440.     REQUIREMENTS
  441.         - You need at least Kick/WB 3.0.
  442.           | Many people wrote me that they cannot find an
  443.           | "animation.datatype" class.
  444.           | Only the 3.1 release contains it. (Subclasses of)
  445.           | animation.datatype can run under 3.0.
  446.  
  447.         - "datatypes/animation.datatype", >= V41
  448.           "animation.datatype V41" requires itself some
  449.           libraries/boopsi classes:
  450.         - "realtime.library", >= V39              - for timing
  451.         - "gadgets/tapedeck.gadget" (any version) - for the controls
  452.  
  453.            If you want to attach samples, you need "sound.datatype" >= V39
  454.            and your prefereed subclass (8svx.datatype for IFF 8SVX samples
  455.            etc.).
  456.  
  457.     USAGE
  458.         If the datatypes descriptor file was activated, any attempt to load
  459.         a GIF anim stream using GMultiView, MultiView, AmigaGuide or
  460.         SwitchWindow will load and play the animation. If the source was a
  461.         file, gifanim.datatype loads frames dynamically from disk.
  462.  
  463.         If you want to save the current animation in gifanim.datatype's
  464.         local format, use MultiView's "Project/Save As..." menu (or
  465.         GMultiView's "Project/Save As Raw...").
  466.         gifanim.datatype saves the current animation, starting with the
  467.         current frame as GIF animation.
  468.  
  469.         If you want to attach samples to the animation, you must edit the
  470.         prefs file (ENV:Classes/DataTypes/gifanim.prefs) and add the
  471.         following line:
  472.         VERBOSE SAMPLE="ram:have_a_nice_day.8svx"
  473.         Which loads and attaches the sample "ram:have_a_nice_day.8svx" to
  474.         the animation. See gifanim.datatype.doc/preferences for a complete
  475.         description of the prefs file.
  476.  
  477.     INSTALLATION
  478.         After unpacking this archive:
  479.         Because this version does not include an Installer script, you have
  480.         to do the installation manually through the shell:
  481.  
  482.           - Unpack this archive and copy the "gifanim.datatype" to
  483.             SYS:Classes/DataTypes/:
  484.  
  485.         Copy CLONE FROM "gifanim.datatype" TO
  486.          "SYS:Classes/DataTypes/gifanim.datatype"
  487.  
  488.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  489.             directory.
  490.             If the descriptor already exists, you should not replace it,
  491.             otherwise you may loose "toolnodes" and other settings stored in
  492.             the existing descriptor.
  493.  
  494.      Copy CLONE FROM "GIFANIM(%|.info)" TO DEVS:Datatypes/
  495.  
  496.     SOURCE
  497.         Source is included as an example how to write an
  498.         animation.datatype subclass which deals with things chunky bitmaps
  499.         deltas and an encoder...
  500.  
  501.     AUTHOR
  502.         If you want to blame me, report any bugs, or wants a new version
  503.         send your letter to:
  504.                         Roland Mainz
  505.                         Hohenstaufenstraße 8
  506.                         52388 Nörvenich
  507.                         GERMANY
  508.  
  509.         Phone: (+49)(0)2426/901568
  510.         Fax:   (+49)(0)2426/901569
  511.  
  512.         EMAIL is also available (if you want to send me attachments
  513.         larger than 1MB (up to 5MB, more with my permission):
  514.  
  515.         GISBURN@w-specht.rhein-ruhr.de
  516.  
  517.         Up to May 1998 I'm reachable using this email address, too:
  518.         Reinhold.A.Mainz@KBV.DE
  519.  
  520.         | Please put your name and address in your mails !
  521.         | German mailers should add their phone numbers.
  522.         | See BUGS section above when submitting bug reports.
  523.  
  524.         Sorry, but I can only look once a week for mails.
  525.         If you don't hear something from me within three weeks, please
  526.         send your mail again (but watch about new releases) (problems with
  527.         this email port are caused by reconfigurations, hackers, network
  528.         problems etc.).
  529.  
  530.         The  entire  "gifanim.datatype"  package  may  be  noncommercially
  531.         redistributed, provided  that  the package  is always  distributed
  532.         in it's complete  form (including it's documentation). A small
  533.         copy fee  for media costs is okay but any kind of commercial
  534.         distribution is strictly forbidden without my permission !
  535.         Comments and suggestions how to improve this program are
  536.         generally appreciated!
  537.  
  538.         Thanks to David Junod, who wrote the animation.datatype and lots of
  539.         the datatypes example code, David Koblas for his "giftopnm"
  540.         and other people for their compression formats, Peter McGavin for
  541.         his C2P function, Matt Dillon for his DICE, Olaf 'Olsen' Barthel
  542.         for his help, ideas and some text clips from his documentations.
  543.  
  544. gifanim.datatype/OM_DISPOSE                       gifanim.datatype/OM_DISPOSE
  545.  
  546.     NAME
  547.         OM_DISPOSE -- Delete a gifanim.datatype object.
  548.  
  549.     FUNCTION
  550.         The OM_DISPOSE method is used to delete an instance of the
  551.         gifanim.datatype class. This method is passed to the superclass when
  552.         it has completed.
  553.         This method frees all frame nodes and their contents (bitmaps,
  554.         colormaps, samples etc.)
  555.  
  556.     RESULT
  557.         The object is deleted. 0UL is returned.
  558.  
  559. gifanim.datatype/OM_NEW                               gifanim.datatype/OM_NEW
  560.  
  561.     NAME
  562.         OM_NEW -- Create a gifanim.datatype object.
  563.  
  564.     FUNCTION
  565.         The OM_NEW method is used to create an instance of the
  566.         gifanim.datatype class.  This method is passed to the superclass
  567.         first. After this, gifanim.datatype parses the prefs file and makes
  568.         a scan through the data to get index information. Frame bitmaps are
  569.         loaded if the input stream isn't seekable, colormaps and the first
  570.         frame are loaded immediately.
  571.         If a sample was set in the prefs, it will be loaded and attached
  572.         to the animation.
  573.  
  574.     ATTRIBUTES
  575.         The following attributes can be specified at creation time.
  576.  
  577.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  578.             attribute. Only DTST_FILE and DTST_RAM are supported.
  579.             If any other type was set in a given DTA_SourceType,
  580.             OM_NEW will be rejected.
  581.             Defaults to DTST_FILE.
  582.  
  583.         DTA_Handle -- For DTST_FILE, a BPTR filehandle is expected. This
  584.             handle will be created by datatypesclass depeding on the DTF_#?
  585.             flag, which is DTF_BINARY here.  DTST_FILE, datatypesclass
  586.             creates a file handle from the given DTA_Name and DTA_Handle
  587.             (a BPTR returned by Lock).
  588.             A DTST_RAM (create empty object) source type requires a NULL
  589.             handle.
  590.  
  591.     RESULT
  592.         If the object was created a pointer to the object is returned,
  593.         otherwise NULL is returned.
  594.  
  595. gifanim.datatype/preferences                     gifanim.datatype/preferences
  596.  
  597.    NAME
  598.        preferences
  599.  
  600.    DESCRIPTION
  601.        The "ENV:Classes/DataTypes/gifanim.prefs" file contains global
  602.        settings for the datatype.
  603.        The preferences file is an ASCII file containing one line where the
  604.        preferences can be set.
  605.        It can be superset by a local variable with the same name.
  606.  
  607.        Each line can contain settings, special settings for some projects
  608.        can be set using the MATCHPROJECT option.
  609.        Lines beginning with a '#' or ';' chars are treated as comments.
  610.        Lines are limitted to 256 chars.
  611.  
  612.    TEMPLATE
  613.        MATCHPROJECT/K,VERBOSE/S,MODEID/K/N,
  614.        16BITCHUNKY=24BITCHUNKY=TRUECOLOR/S,
  615.        NO16BITCHUNKY=NO24BITCHUNKY=NOTRUECOLOR/S,FPS/K/N,REPEAT/S,
  616.        NOREPEAT/S,SAMPLE/K,SAMPLESPERFRAME=SPF/K/N,VOLUME/K/N,LOADALL/S,
  617.        NOLOADALL/S
  618.  
  619.        MATCHPROJECT -- The settings in this line belongs only to this
  620.            project(s), e.g. if the case-insensitive pattern does not match,
  621.            this line is ignored.
  622.            The maximum length of the pattern is 128 chars.
  623.            Defaults to #?, which matches any project.
  624.  
  625.        VERBOSE -- Print information about the animation. Currently
  626.           the frame numbers and the used compression are printed, after all
  627.           number of scanned/loaded frames, set FPS rate, dimensions (width/
  628.           height/depth), sample information etc.
  629.  
  630.        MODEID -- Select screen mode id of datatype (will be stored in
  631.            ADTA_ModeID). Note that the DOS ReadArgs function used for parsing
  632.            fetches a SIGNED long. The bit 31 will be represented by minus
  633.            '-'. (example: "MODEID=266240" sets the mode to the A2024 screen
  634.            mode id)
  635.            Defaults to -1, which means: Use the best screenmode available for
  636.            the given width, height and depth.
  637.  
  638.        16BITCHUNKY
  639.        24BITCHUNKY
  640.        TRUECOLOR -- Create 24 bit chunky bitmaps, if possible.
  641.            Note that the 16BITCHUNKY and the 24BITCHUNKY options will be
  642.            seperated in the future. The TRUECOLOR option selects the
  643.            best truecolor depth in this case...
  644.  
  645.        NO16BITCHUNKY
  646.        NO24BITCHUNKY
  647.        NOTRUECOLOR -- Turns 24BITCHUNKY option off. (Default)
  648.            Note that the 16BITCHUNKY and the 24BITCHUNKY options will be
  649.            seperated in the future. The TRUECOLOR option selects the
  650.            best truecolor depth in this case...
  651.  
  652.        FPS -- Frames Per Second
  653.            A value of 0 here means: Use default FPS.
  654.  
  655.        REPEAT -- Turn on repeat mode, e.g. DTA_Repeat == TRUE
  656.  
  657.        NOREPEAT -- Turns REPEAT mode off.
  658.  
  659.        SAMPLE -- Attach the given sample to the animation. The sample will
  660.            be loaded using datatypes (GID_SOUND).
  661.            Only one sample can be attached to one animation stream, any
  662.            following attempt to attach a sample will be ignored.
  663.  
  664.        SAMPLESPERFRAME -- Set samples per frame rate for sound. This
  665.            overrides the own internal calculations to get rid of rounding
  666.            errors.
  667.  
  668.        VOLUME -- Volume of the sound when playing.
  669.            Defaults to 64, which is the maximum. A value greater than 64 will
  670.            be set to 64.
  671.  
  672.        LOADALL -- Load all frames into memory.
  673.  
  674.        NOLOADALL -- Turns off the LOADALL flag, which may be set in a prefs-
  675.            line before. This switch is set per default, and can be turned off
  676.            by the LOADALL option, later it can be turned on again by this
  677.            option.
  678.  
  679.    NOTE
  680.        - An invalid prefs file line will be ignored and forces the VERBOSE
  681.          output.
  682.  
  683.        - REPEAT mode may be a hack.
  684.  
  685.    BUGS
  686.        - Low memory may cause that the prefs file won't be parsed.
  687.  
  688.        - Lines are limitted to 256 chars
  689.  
  690.        - An invalid prefs file line will be ignored.
  691.  
  692.        - The sample path length is limitted to 200 chars. A larger
  693.          value may crash the machine if an error occurs.
  694.  
  695.