home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 106 / af106sub.adf / datatypes.LZX / animation_datatype / animation.datatype.doc < prev    next >
Text File  |  2003-05-15  |  56KB  |  1,527 lines
  1. TABLE OF CONTENTS
  2.  
  3. animation.datatype/--datasheed--
  4. animation.datatype/--model--
  5. animation.datatype/ADTM_LOCATE
  6. animation.datatype/ADTM_PAUSE
  7. animation.datatype/ADTM_START
  8. animation.datatype/ADTM_STOP
  9. animation.datatype/DTM_COPY
  10. animation.datatype/DTM_FRAMEBOX
  11. animation.datatype/DTM_PRINT
  12. animation.datatype/DTM_PROCLAYOUT
  13. animation.datatype/DTM_REMOVEDTOBJECT
  14. animation.datatype/DTM_TRIGGER
  15. animation.datatype/DTM_WRITE
  16. animation.datatype/GM_GOACTIVE
  17. animation.datatype/GM_GOINACTIVE
  18. animation.datatype/GM_HANDLEINPUT
  19. animation.datatype/GM_HELPTEST
  20. animation.datatype/GM_HITTEST
  21. animation.datatype/GM_LAYOUT
  22. animation.datatype/GM_RENDER
  23. animation.datatype/MAIN
  24. animation.datatype/ObtainAnimationEngine
  25. animation.datatype/OM_DISPOSE
  26. animation.datatype/OM_GET
  27. animation.datatype/OM_NEW
  28. animation.datatype/OM_SET
  29. animation.datatype/OM_UPDATE
  30. animation.datatype/preferences
  31. animation.datatype/--datasheed--             animation.datatype/--datasheed--
  32.  
  33.     NAME
  34.         animation.datatype -- base datatype for animations
  35.  
  36.     SUPERCLASS
  37.         datatypesclass
  38.  
  39.     DESCRIPTION
  40.         The animation.datatype is the super-class for any animation related
  41.         classes.
  42.  
  43.         This class is responsible for creating the controls, scaling,
  44.         remapping and synchronization.
  45.  
  46.     METHODS
  47.         OM_NEW -- Create a new animation object. Passed to superclass, then
  48.             create internal resurces, then fall througth OM_SET.
  49.  
  50.         OM_GET -- Obtain the value of an attribute. Passed to superclass
  51.             if the attribute is not recognized by animation.datatype class.
  52.  
  53.         OM_SET -- Set the values of multiple attributes. Passed to 
  54.             superclass first.
  55.  
  56.         OM_UPDATE -- Update the values of multiple attributes. Falls 
  57.             througth to OM_SET.
  58.  
  59.         OM_NOTIFY -- Notify new attributes. Passed to superclass.
  60.  
  61.         OM_DISPOSE -- Dispose of a animation object. Passed to superclass
  62.             after animation.datatype instance has freed it's resources.
  63.  
  64.         GM_LAYOUT -- Layout the object and notify the application of the
  65.             title and size. Passed to superclass first.
  66.  
  67.         GM_HITTEST -- Determine if the object has been hit with the
  68.             mouse within the gadget domain rectange. Overrides the
  69.             superclass.
  70.  
  71.         GM_HELPTEST -- Determinate if the object has been hit by an help
  72.             test within the gadget help domain rectangle. Overrides the
  73.             superclass.
  74.  
  75.         GM_GOACTIVE -- Tell the object to go active. Overrides the
  76.             superclass.
  77.  
  78.         GM_HANDLEINPUT -- Handle input. Overrides the superclass.
  79.  
  80.         GM_GOINACTIVE -- Inactive the object. Overrides the superclass.
  81.  
  82.         GM_RENDER -- Cause the current frame to render.
  83.  
  84.         DTM_FRAMEBOX -- Obtain or set the display environment that the
  85.             animation requires. Passed to superclass first.
  86.  
  87.         DTM_PROCLAYOUT -- Layout object on application process. See
  88.             GM_LAYOUT for functionality.
  89.  
  90.         DTM_REMOVEDTOBJECT -- Remove an object from the window/screen.
  91.             Passed to superclass after all.
  92.  
  93.         DTM_TRIGGER -- Cause an async event to occur.
  94.             Overrides the superclass.
  95.  
  96.         DTM_OBTAINDRAWINFO -- not implemented yet
  97.  
  98.         DTM_DRAW -- not implemented yet
  99.  
  100.         DTM_RELEASEDRAWINFO -- not implemented yet
  101.  
  102.         DTM_COPY -- Copy the current frame to the clipboard as an IFF ILBM
  103.             picture.
  104.             Overrides the superclass.
  105.  
  106.         DTM_WRITE -- Write the current or a specified frame to a file as an
  107.             IFF ILBM picture.
  108.             Overrides the superclass.
  109.  
  110.         DTM_PRINT -- Print the current or a specified frame.
  111.             Overrides the superclass.
  112.  
  113.         ADTM_LOADFRAME -- Load a frame of the animation.
  114.  
  115.         ADTM_UNLOADFRAME -- Deallocate any memory allocated by
  116.             ADTM_LOADFRAME.
  117.  
  118.         ADTM_START -- Start the animation.  This MUST be passed to the
  119.             super-class AFTER the sub-class has started.
  120.  
  121.         ADTM_PAUSE -- Pause the animation.  This MUST be passed to the
  122.             super-class BEFORE the sub-class pauses.
  123.  
  124.         ADTM_STOP -- Stop the animation.  This MUST be passed to the
  125.             super-class BEFORE the sub-class stops.
  126.  
  127.         ADTM_LOCATE -- Used to locate a frame of the animation.
  128.  
  129.         All other methods are passed to the superclass.
  130.  
  131.     ATTRIBUTES
  132.         OBP_Precison (ULONG) -- Precision to use when obtaining colors.
  133.             See the PRECISION_ defines in <graphics/view.h>.
  134.             Fixed to PRECISION_ICON (V40),
  135.             Defaults to PRECISION_IMAGE V41).
  136.  
  137.             Applicability is () (V40)
  138.             Applicability is (ISG) (V41)
  139.  
  140.         DTA_ControlPanel (BOOL) -- Determine whether the control
  141.             panel is shown.  Defaults to TRUE.
  142.  
  143.             Applicability is (I).
  144.             Applicability is (ISGU) (V41)
  145.  
  146.         DTA_Repeat (BOOL) -- Determine whether the animation
  147.             should repeat playing.  Defaults to FALSE.
  148.  
  149.             Applicability is (ISGU) (V41)
  150.  
  151.         DTA_Immediate (BOOL) -- Indicate whether the animation
  152.             should immediately begin playing.  Defaults to
  153.             FALSE.
  154.  
  155.             Applicability is (I).
  156.             Applicability is (ISGU) (V41)
  157.  
  158.         ADTA_ModeID (ULONG) -- Set and get the graphic mode id of the
  159.             picture. The mode id set here will be checked by BestModeIDA
  160.             based on width/height/depth info of the animation.
  161.             Defaults to 0.
  162.  
  163.             Applicability is (ISG).
  164.  
  165.         ADTA_KeyFrame (struct BitMap *) -- Pointer to the key
  166.             frame.
  167.  
  168.             This bitmap should be allocated using AllocBitMap because this
  169.             is the only way to force GetBitMapAttr and other functions to
  170.             return correct attributary flags.
  171.  
  172.             This bitmap will be used for internal calculations and
  173.             assumtions about bitmap data layout; the bitmaps got from
  174.             ADTM_LOADFRAME have the same size and layout, but GetBitMapAttr
  175.             may return wrong values for these bitmaps!
  176.  
  177.             Applicability is (ISG).
  178.  
  179.         ADTA_ColorRegisters (struct ColorRegister *) -- Color table.
  180.  
  181.             Applicability is (G).
  182.  
  183.         ADTA_CRegs (ULONG *) -- Color table to use with SetRGB32CM().
  184.  
  185.             Applicability is (G).
  186.  
  187.         ADTA_GRegs (ULONG *) -- Color table (like ADTA_CRegs, but contains
  188.             color values of allocated (shared) pens).
  189.  
  190.             Applicability is (G).
  191.  
  192.         ADTA_ColorTable (ULONG *) -- PRIVTAE
  193.         ADTA_ColorTable2 (ULONG *) -- PRIVATE
  194.  
  195.             Applicability is (G).
  196.  
  197.         ADTA_Allocated (ULONG) --  Number of shared colors allocated.
  198.  
  199.              Applicability is (G).
  200.  
  201.         ADTA_NumColors (WORD) -- Number of colors used by the picture.
  202.  
  203.             Applicability is (ISG).
  204.  
  205.         ADTA_NumAlloc (WORD) -- Number of colors allocated by the picture.
  206.  
  207.             Applicability is (G).
  208.  
  209.         ADTA_Remap (BOOL) -- Indicate whether the animation should be
  210.             remapped or not.
  211.             Defaults to TRUE.
  212.  
  213.             Applicability is (IS).
  214.             Applicability is (ISG) (V41).
  215.  
  216.         ADTA_Screen (struct Screen *) -- Screen to remap to
  217.  
  218.             Applicability is (IS) (V41).
  219.  
  220.         ADTA_NumSparse (UWORD) -- Number of colors used for sparse remapping
  221.  
  222.             Applicability is (IS) (V41).
  223.  
  224.         ADTA_SparseTable (UBYTE *) -- Pointer to a table of pen numbers
  225.             indicating which colors should be used when remapping the image.
  226.             This array must contain as many entries as there
  227.             are colors specified with ADTA_NumSparse
  228.  
  229.             Applicability is (IS) (V41).
  230.  
  231.         ADTA_Width (ULONG) -- Width of a frame in pixels.
  232.  
  233.             Applicability is (ISG).
  234.  
  235.         ADTA_Height (ULONG) -- Height of a frame in pixels.
  236.  
  237.             Applicability is (ISG).
  238.  
  239.         ADTA_Depth (ULONG) -- Depth of the frame.
  240.  
  241.             Applicability is (ISG).
  242.  
  243.         ADTA_Frames (ULONG) -- Number of frames in animation.
  244.             Defaults to 0,
  245.             setting this attribute also affects ADTA_FrameIncrement
  246.             (e.g. set it's to 10 except if ADTA_Frames < 50, then
  247.             ADTA_FrameIncrement = ADTA_Frames / 5).
  248.  
  249.             Applicability is (ISG).
  250.  
  251.         ADTA_Frame (ULONG) -- Currect frame
  252.             Setting of this attribute causes an ADTM_LOCATE !
  253.  
  254.             Applicability is (G).
  255.             Applicability is (SGU) (V41)
  256.  
  257.         ADTA_FramesPerSecond (ULONG) -- Number of frames per
  258.             second to play.
  259.             V40 limits this to 60 fps, V41 increases the limit up to
  260.             1200 fps (max. realtime.library resolution).
  261.             Defaults to 10.
  262.  
  263.             Applicability is (ISG).
  264.  
  265.         ADTA_TicksPerFrame (ULONG) -- realtime.library ticks per frame
  266.             Defaults to TICK_FREQ / 10 = 120
  267.  
  268.             Applicability is (ISG).
  269.  
  270.         ADTA_CurrFramesPerSecond (ULONG) -- current frames per second rate
  271.             The playback rate and sound playback speed are recalculated
  272.             to match this value.
  273.             If ADTA_AdaptiveFPS is TRUE, this value is recalculated to
  274.             allow the maximum available playback speed on the hardware
  275.             (limmitted by ADTA_FramesPerSecond)
  276.  
  277.             Applicability is (ISGU).
  278.  
  279.         ADTA_CurrTicksPerSecond (ULONG) -- current ticks per second rate
  280.             The playback rate and sound playback speed are recalculated
  281.             to match this value.
  282.             If ADTA_AdaptiveFPS is TRUE, this value is recalculated to
  283.             allow the maximum available playback speed on the hardware
  284.             (limmitted by ADTA_TicksPerSecond)
  285.  
  286.             Applicability is (ISGU).
  287.  
  288.         ADTA_FrameIncrement (ULONG) -- Amount to change frame by when fast
  289.             forwarding or rewinding.
  290.             Defaults to 10
  291.  
  292.             Applicability is (G).
  293.             Applicability is (SGU) (V41)
  294.  
  295.         ADTA_BitMapHeader (struct BitMapHeader *) -- Set and get the
  296.             base information for the animation.  BitMapHeader is defined in
  297.             <datatypes/pictureclass.h>
  298.             Setting this tag causes the given struct BitMapHeader to be copie
  299. d
  300.             into the object.
  301.             This also causes ADTA_Width, ADTA_Height, ADTA_Depth to be set.
  302.  
  303.             Applicability is (G).
  304.             Applicability is (ISG) (V41)
  305.  
  306.         ADTA_Sample (BYTE *) -- Pointer to sample data.
  307.  
  308.             Applicability is (ISG).
  309.  
  310.         ADTA_SampleLength (ULONG) -- Length of sample data.
  311.  
  312.             Applicability is (ISG).
  313.  
  314.         ADTA_Period (ULONG) -- Period to play back sample at.
  315.             Defaults to 360.
  316.  
  317.             Applicability is (ISG).
  318.  
  319.         ADTA_Volume (ULONG) -- Volume to play back sample at.
  320.             Defaults to 64.
  321.  
  322.             Applicability is (ISG).
  323.             Applicability is (ISGU) (V41).
  324.  
  325.         ADTA_Cyles (ULONG) -- Cycles to play.
  326.             Defaults to 1.
  327.  
  328.             Applicability is (G).
  329.  
  330.         ADTA_AdaptiveFPS (BOOL) -- If TRUE, the playback rate is limitted
  331.             to the maximum reachable playback rate without frame skipping.
  332.  
  333.             Defaults to TRUE, but maybe changed using the prefs-file (V41).
  334.  
  335.         ADTA_SmartSkip (BOOL) -- If TRUE, some frames are skipped based
  336.             on internal statistics to keep playback and sound in sync.
  337.  
  338.             Defaults to FALSE, but maybe changed using the prefs-file (V41).
  339.  
  340.         ADTA_NumPrefetchFrames (ULONG) -- Number of frames to be
  341.             prefetched by the loading process.
  342.  
  343.             Defaults to 10, but maybe changed using the prefs-file (V41).
  344.  
  345.         ADTA_OvertakeScreem (BOOL) -- Overtake screen palette when not
  346.             remapping.
  347.             Applications should set this explicitly to FALSE if they don't
  348.             want to be affected by this datatype.
  349.  
  350.             Defaults to TRUE, but maybe changed using the prefs-file (V41).
  351.  
  352.     BUGS
  353.         Horrors. This alpha (V41.3) version suffers under the 1001
  354.         nightmare bugs problem:
  355.  
  356.         After all, I think the current version has the following bugs:
  357.  
  358.         - The CPU blitter support is currently broken. Instead of doing
  359.           a small speed comparisation between OS blitter and CPU blitter
  360.           the CPU blitter is enabled on a mc68030 per default if remapping
  361.           is required.
  362.           Who likes to use the CPU blitter evertimes, set explicitly the
  363.           CPUBLITTER switch in the prefs file, to turn off the CPU blitter
  364.           evertimes is the OSBLITTER option.
  365.  
  366.         - timing may be slightly inaccurate. On a rate of 10 fps, this
  367.           isn't bad, but using fps >= 1 or lower (e.g.
  368.           ADTA_TicksPerFrame > 1200), you may see the problem.
  369.  
  370.         - ADTA_OvertakeScreen does not work correctly. Currently it is
  371.           always set to TRUE.
  372.  
  373.         - Internal statistics (for ADTA_AdaptiveFPS, ADTA_SmartSkip etc.)
  374.           are working now, but the wheighting of loading and display time
  375.           can be made better.
  376.  
  377.         - ADTA_SmartSkip code has been disabled.
  378.  
  379.         - CyberGFX code has been disabled because it isn't tested yet.
  380.  
  381.         - Incompatible with the current V41.11 cgxsystem.library 
  382.           PLANES2FAST option, because the GetBitMapAttr function does not 
  383.           BMF_STANDARD flag and then animation.datatype treats the bitmaps 
  384.           as non-planar, which cannot be remapped.
  385.  
  386.         - planar bitmaps with depth > 8 are not supported yet, sorry.
  387.  
  388.         - tapedeck.gadget handling is very tricky, and may have some
  389.           problems.
  390.  
  391.         - On a highly loaded system the animation playback can't be
  392.           stopped on the fly (IPC communication has problems with this).
  393.           This happens often when DTA_Repeat is set, and the
  394.           ADTM_STOP, ADTM_START cycle occurs to rewind the animation.
  395.  
  396.         - IPC communication is __VERY__ complex. We have 5 (!) threads
  397.           to be controlled and sync'ed:
  398.           - loader process
  399.           - display and control process
  400.           - input.device
  401.           - application process
  402.           - realtime.library player interrupt
  403.  
  404.           Don't expect that all works fine here...
  405.  
  406.         - DTA_Repeat == TRUE does not work with anims with less than 3
  407.           frames, because the first frame is skipped.
  408.           This causes problems with (for example) 2 frame gif animations.
  409.  
  410.         - ADTA_NumSpase and ADTA_SparseTable does not work yet, sorry.
  411.  
  412.     TODO
  413.         - In HAM-mode, a box of color 0 should be drawn around the object
  414.           to avoid some ugly HAM-effects when the background of the parent
  415.           window is not 0.
  416.           (Idea was taken from "cdgsxl").
  417.  
  418.         - Remapping code HAM -> 24-bit
  419.  
  420.         - Remapping code EHB -> Other amiga modes
  421.  
  422.         - Support for non-planar bitmap types (chunkypixel etc.).
  423.  
  424.         - Support for 12/15/16/18/21/24-bit planar bitmaps (direct-RGB 
  425.           coded).
  426.  
  427.         - Get some more info about the mysterious tapedeck.gadget.
  428.  
  429.         - The CBM OS 3.1 tapedeck.gadget is limmited to a height of 16
  430.           pixels. If I have time, I can write my own version WITHOUT this
  431.           limmitation...
  432.  
  433.     HISTORY
  434.         V41.1
  435.           - Initial release to DataTypes Mailinglist
  436.  
  437.         V41.2
  438.           - Recompiled with SAS/C 6.58; this may fix mc68060 related
  439.             problems.
  440.  
  441.           - Now the tapedeck update is slightly better because a "magic"
  442.             update (using a gpr_Redraw of 100 instead of GREDRAW_UPDATE)
  443.             is used.
  444.             Thanks to Heinz Wrobel.
  445.  
  446.           - Fixed the bug that after resizing the parent window the
  447.             height of the playback area was not restored. Fixed.
  448.  
  449.           - If the display screen is not visible, the old V40.6 turns
  450.             of the bitmap display (using the VP_HIDE flags).
  451.             Now V41 does the same.
  452.             Thanks to Heinz Wrobel for explaining this. Because this
  453.             may be a hack (not documented by the OS docs), this
  454.             feature is turned off if the NOHACKS switch is set in the
  455.             prefs file.
  456.  
  457.           - Fixed internal statistics (used for adaptive playback rate
  458.             calculations). Now the datatype tracks time-to-unload-a-frame,
  459.             too.
  460.  
  461.           - Fixed a problem with adaptive playback rate selection
  462.             and dynamic timing. The new model seems to run more smoothly,
  463.             but this is still a weak point.
  464.  
  465.           - Recompiled the project with DATA=FARONLY. I think that this
  466.             should fix some problems.
  467.             Thanks to Steve Krueger (sekruege@nando.net) for answering
  468.             some questions.
  469.  
  470.           - Moved OS vs. CPU blitter selection code from GM_LAYOUT
  471.             to the first GM_RENDER after GM_LAYOUT. This should be more
  472.             reliable, and speeds up the initial window layout a little
  473.             bit.
  474.  
  475.           - Seems that there is a bug in the CPU blitter (selection) code.
  476.             For now I wrote a small workaround; the CPU blitter is
  477.             enabled per default on a mc68030 if ADTA_Remap is set to TRUE
  478.             (assuming that the cpu blitter function running on a mc68030 is 
  479.             a little bit faster than the OS blitter).
  480.  
  481.           - Updated the autodocs.
  482.  
  483.           - OM_DISPOSE now preserves result2 (e.g. IoErr() result)
  484.             explicitly.
  485.  
  486.           - OM_DISPOSE now sets the embedded sound.datatype object's
  487.             SDTA_Sample to NULL. This fixes possibly problems if a
  488.             sound.datatype clone tries to FreeVec' the sample...
  489.  
  490.           - Removed code from OM_DISPOSE which is executed in
  491.             DTM_REMOVEDTOBJECT (e.g. freeing of pens and tmp. bitmaps).
  492.  
  493.           - Now OM_GET ADTA_Sample, ADTA_SampleLength, ADTA_Period, 
  494.             ADTA_Volume and ADTA_Cycles are got from the current frame.
  495.             This feature should work now.
  496.  
  497.           - Implemeted OM_GET ADTA_DestFrame (alias PDTA_DestBitMap). Note 
  498.             that accessing this bitmap is ONLY safe when the object does not
  499.             do any playback; the same rule must be respected for
  500.             ADTA_Sample, ADTA_SampleLength and ADTA_Period.
  501.  
  502.           - Added CBM cdxl.datatype compatibility hack (I'm __very__ angry
  503.             about this problem because it took a long time to find the
  504.             problem). It seems that CBM's cdxl.datatype requires that it's
  505.             instance data are on long-word boundary because the data starts
  506.             with a FileInfoBlock.
  507.             Don't rely on this feature !!!
  508.  
  509.           - If the object setup (OM_NEW) failed in a sub-process, the error
  510.             code is now passed to the parent process and there stored
  511.             in Result2. This includes realtime.library errors, too.
  512.  
  513.           - Now uses AllocPooled and an internal memory management to
  514.             avoid memory allocations whereever and whenever possible.
  515.  
  516.           - Internal divisions are now rounded when usefull.
  517.  
  518.           - Child processes are now starting in sequence instead of a
  519.             parallel setup. This is only for testing; later I'll write the
  520.             parallel setup again.
  521.  
  522.           - Fixed the bug that GM_RENDER with GREDRAW_REDRAW didn't work 
  523.             properly if the parents box was only changed of one of X- OR 
  524.             the Y-axis (e.g. EraseRect wasn't done in this case).
  525.  
  526.           - Fixed the bug that tapedeck.gadget was drawn even if the
  527.             DTA_Domain height was below GA_Height (tapedeck.gadget can't
  528.             clip in Y-direction).
  529.             This fixes visual problems with embed.datatype.
  530.             The check is also made in GM_HITTEST, GM_HELPTEST and
  531.             GM_GOACTIVE.
  532.  
  533.           - If DTA_ControlPanel is FALSE and the mouse SELECTUP starts the
  534.             playback, a following mouse SELECTUP now pauses the playback.
  535.  
  536.           - The stack swapping code now allocates it's memory without
  537.             MEMF_CLEAR, which should result in a small speedup when doing
  538.             things.
  539.  
  540.           - The library base now has 16 reserved lvo entries after
  541.             ObtainEngine which returns all 0 for now.
  542.             All these entries are reserved and private for now.
  543.  
  544.           - DTM_REMOVEDTOBJECT now passes the msg to superclass after doing
  545.             it's work. This fixes problems with some datatypesclass
  546.             internals.
  547.             Fixed.
  548.  
  549.           - DTM_FRAMEBOX now passes the msg to superclass before doing
  550.             it's work. Now datatypesclass can release the input clipboard
  551.             which avoids that the clipboard unit is locked while the object
  552.             exists.
  553.             Fixed.
  554.  
  555.           - Fixed the bug that setting ADTA_ModeID to INVALID_ID caused
  556.             havoc in the object (remapping code got turned off, the
  557.             palette of a public screen was changed etc.).
  558.             Now a ADTA_ModeID of INVALID_ID is treated as a 0UL mode id.
  559.             Thanks to Francis Labrie (fb691875@er.uqam.ca) for reporting
  560.             the bug.
  561.             Fixed.
  562.  
  563.           - Fixed the bug that when the CPU blitter draws the display, a
  564.             GM_RENDER showed the first frame. Now a GM_RENDER and other
  565.             methods sync's the ADTA_DestFrame bitmap correctly (e.g. copy
  566.             the (remapped) src bitmap) into ADTA_DestFrame) before using it.
  567.             Fixed.
  568.  
  569.           - Changed some internals that moving the tapedeck.gadget's slider
  570.             causes less overhead when loading single frames.
  571.  
  572.           - Now the animation.datatype instance data contents are on a
  573.             long-word aligned boundary, which should speed up some things.
  574.             (Tested only with Kick 3.0 yet).
  575.  
  576.           - Fixed a bug in the ADTA_OvertakeScreen code that caused that
  577.             the last color in a palette change was set to black instead
  578.             of the wanted color.
  579.             Fixed.
  580.  
  581.         V41.3
  582.           INTERNAL RELEASE
  583.  
  584.           - Fixed the bug that a non-planar (chunky) bitmaps wasn't passed
  585.             througth.
  586.  
  587.           - Improved internal GetPictureCopy (which is used to create the
  588.             temp. object for DTM_COPY, DTM_WRITE, DTM_PRINT):
  589.             - It now uses the key bitmap as a friend bitmap parameter.
  590.               This may fix problems when processing non-planar bitmaps.
  591.  
  592.               WARNING: This may result in large problems if a < V43
  593.               picture.datatype is used in a GFX-card environment (CyberGFX,
  594.               Picasso 96 etc.).
  595.  
  596.             - It now does not attempt to copy a colormap if is
  597.               ADTA_NumColors == 0 (added this check to avoid some
  598.               unneccesary memory copies which result all in a big NOP is
  599.               this case).
  600.  
  601.           - Reduced the memory usage if non-planar input bitmaps are used
  602.             by the subclass (the temporary bitmaps used for remapping etc.
  603.             are not allocated (because they were not used...)).
  604.  
  605.           - Tests have shown that the PLANES2FAST option of
  606.             cgxsystem.library V41.11 is incompatible with animation.datatype
  607.             because the GetBitMapAttr function does not set BMF_STANDARD for
  608.             these bitmaps even if they are planar.
  609.             This causes that the bitmaps are treated as chunkypixel ones
  610.             (where the remapping code can't touch them).
  611.             Cannot be fixed yet.
  612.  
  613.         V41.4
  614.           Version for the "Compuler 97'" fair in Colone/Germany
  615.  
  616.           - Replaced the custom stack swapping code by my "standard" module
  617.  
  618.           - Fixed the bug that a failed palette allocation (e.g. setting of
  619.             ADTA_NumColors) return random values for the ADTA_CRegs, 
  620.             ADTA_ColorRegisters etc. attributes if it was set more than once
  621.             in objects lifetime and the allocation failes.
  622.             The attributes now return correctly NULL in this case.
  623.             Fixed.
  624.  
  625.           - If ADTA_NumColors is set to 0, now ADTA_CRegs,
  626.             ADTA_ColorRegisters, ADTA_GRegs etc. return a NULL pointer
  627.             instead of returning radom values.
  628.  
  629.           - Minor code cleaup.
  630.  
  631.           - Oops, the last distribution missed the
  632.             "datatypes/animationclassext.h" include file.
  633.  
  634.     SEE ALSO
  635.         mpegsystem.datatype, mpegvideo.datatype,
  636.         picmovie.datatype,
  637.         cdxl.datatype. avi.datatype, quicktime.datatype,
  638.         moviesetter.datatype,
  639.         film.datatype
  640.  
  641.     THANKS TO
  642.         David Junod for the design and the first implemenation,
  643.         Olaf Barthel for his great help,
  644.         Heinz Wrobel for explaining some things.
  645.         Frank Mariak for his CPU blitter replacement and CyberGFX support,
  646.         Niels Froeling for the planar remapping code,
  647.         and the people of the DataTypes Mailing list for testing and their
  648.         help
  649.  
  650. animation.datatype/--model--                     animation.datatype/--model--
  651.  
  652.     MODEL
  653.         <The following has not been finished yet. It's only a first, small,
  654.         poorly, genernal overview about the used model>
  655.  
  656.         The following short text should describe how the animation.datatype
  657.         works (in general):
  658.  
  659.         The animation.datatype is split up in four parts:
  660.          1. the decoder (the subclass which sits on animation.datatype)
  661.          2. the loading process
  662.          3. the display and control process
  663.          4. a realtime.library Player (timing interrupt)
  664.          5. a control process (application process, or input.device)
  665.  
  666.       1. The Decoder
  667.          The decoder part belongs completely to the subclass (sitting on
  668.          animation.datatype). animation.datatype communicates through
  669.          methods (ADTM_START, ADTM_PAUSE, ADTM_STOP, ADTM_LOCATE,
  670.          ADTM_LOADFRAME and ADTM_UNLOADFRANE) with the subclass.
  671.          Mainly, ADTM_LOADFRAME and ADTM_UNLOADFRAME are used to load/unload
  672.          a frame from the subclass.
  673.  
  674.       2. The Loading Process
  675.          The loading process has a simple task: Load as much frames as
  676.          possible and store the frames into a "frame queue".
  677.          The idea is that the loading process (which runns at a lower
  678.          priority than the display process) consumes all CPU time which is
  679.          not used by the display process.
  680.  
  681.          The load process is controlled by the display and the control
  682.          process (the application., for example), which can set one of
  683.          the following modes for the load process:
  684.          a) preload: Load the next 10 (can be changed by the prefs-file)
  685.                      frames, then stop.
  686.          b) play:    Fill the "frame queue" until it is full (e.g. until
  687.                      it reaches 10 frames or more).
  688.          c) stop:    Stop loading and preloading
  689.          d) flush:   flush frame queue
  690.  
  691.       3. The Display Process
  692.          The display process is responsible for remapping and displaying
  693.          of frames during playback. If signalled by the realtime.library
  694.          Player, the display process gets the first frame from the frame
  695.          queue, remapps it (if neccesary) and displays it. If a sample
  696.          is attached to the frame, the sample is fed to the embedded
  697.          sound.datatype object.
  698.  
  699.       4. The realtime.library Player (Timing Interupt)
  700.          The player has the job to decrase a counter each 1/1200 sec.
  701.          If the counter reaches 0, it is time to display the next frame,
  702.          and the interrupt fires a signal to the display process to
  703.          trigger the display of the frame.
  704.  
  705.       5. The Control Process
  706.          There is no fixed control process. But the application is allowed 
  707.          to send ADTM_START, ADTM_PAUSE, ADTM_STOP and ADTM_LOCATE to
  708.          trigger a playback, pause or stop it - or locate a single frame.
  709.          The same counts for the user, who plays with the embedded
  710.          tapedeck.gadget.
  711.  
  712. animation.datatype/ADTM_LOCATE                 animation.datatype/ADTM_LOCATE
  713.  
  714.     NAME
  715.         ADTM_LOCATE -- Locate a frame
  716.  
  717.     FUNCTION
  718.         ADTM_LOCATE locates a frame and displays it.
  719.  
  720.     RESULT
  721.         Returns non-zero on success,
  722.         0UL on failure.
  723.  
  724.     NOTE
  725.  
  726. animation.datatype/ADTM_PAUSE                   animation.datatype/ADTM_PAUSE
  727.  
  728.     NAME
  729.         ADTM_PAUSE -- Pause an animation playback
  730.  
  731.     FUNCTION
  732.         ADTM_PAUSE pauses an animation playback.
  733.         If the playback is currently active, it will be paused, then the
  734.         sound is turned off. The load process is turned off, too.
  735.  
  736.     RESULT
  737.         Non-zero if the playback has been turned off successfully.
  738.         0UL if on error (object is not attached to a window etc.).
  739.  
  740.     NOTE
  741.         - This method MUST be passes to the super-class (animation.datatype)
  742.           before the sub-class pauses !
  743.  
  744.         - Subclasses can treat this method like ADTM_STOP. Unlike
  745.           ADTM_STOP, a subclass should not reset any frame counter
  746.           (or Seek to any other file position, for example), because
  747.           in the most cases the playback starts again at this position.
  748.  
  749. animation.datatype/ADTM_START                   animation.datatype/ADTM_START
  750.  
  751.     NAME
  752.         ADTM_START -- Start animation playback
  753.  
  754.     FUNCTION
  755.         ADTM_START starts the animation playback.
  756.  
  757.         First the timer is reset to the current frame. If the load process
  758.         is inactive, it will be activated; this method waits until
  759.         a preload cycle is done.
  760.         Then the timer is activated and sound will be turned on.
  761.  
  762.         Starting with V41, this method is a NOP when the object is not
  763.         attached to a window/requester (this allows custom players
  764.         to use ADTM_START and the subclass optimisations made in a
  765.         ADTM_START / ADTM_STOP cycle).
  766.  
  767.     RESULT
  768.         Returns Non-Zero if playback has been started successfulls.
  769.         Returns 0UL on failure (e.g. objectnot attached to a window etc.)
  770.  
  771.     NOTE
  772.         - Subclasses can use ADTM_START to optimize playback. Starting
  773.           with ADTM_START and ADTM_PAUSE/ADTM_STOP, a continous range
  774.           of frames is read by the loading process.
  775.           A common example usage (in a subclass) is to send the first
  776.           read-packets (for the timstamp given in adtStart -> asa_Frame)
  777.           asyncrounous to the filesystem.
  778.           Don't wait for the packets ! ADTM_LOADFRAME should do this.
  779.  
  780.         - Subclasses must prepare for playback BEFORE passing
  781.           this msg to animation.datatype, because the loading process will
  782.           immediately start loading.
  783.  
  784.         - Subclasses MUST NOT hold any locks which are also locked in
  785.           ADTM_LOADFRAME / ADTM_UNLOADFRAME when passing ADTM_START to
  786.           animation.datatype. This causes a deadlock because the process
  787.           which is running ADTM_START will wait until the load process
  788.           has finished it's playback, but the load process is waiting
  789.           for the semaphore which is locked by the ADTM_START process.
  790.  
  791.         - Starting with V41, this method gurantees that the playback
  792.           has been started on exit.
  793.  
  794.         - Starting with V41, this method is safe when the object is
  795.           not attached to a window.
  796.  
  797. animation.datatype/ADTM_STOP                     animation.datatype/ADTM_STOP
  798.  
  799.     NAME
  800.         ADTM_STOP -- Stops an animation.datatype playback
  801.  
  802.     FUNCTION
  803.         ADTM_STOP stops an animation playback.
  804.         If the playback is currently active, it will be stopped, then the
  805.         sound is turned off. The load process is turned off, too.
  806.  
  807.     RESULT
  808.  
  809.     NOTE
  810.         - This method MUST be passes to the super-class (animation.datatype)
  811.           before the sub-class stops !
  812.  
  813.         - Starting with V41 this method gurantees that the playback has
  814.           been stopped on exit.
  815.  
  816. animation.datatype/DTM_COPY                       animation.datatype/DTM_COPY
  817.  
  818.     NAME
  819.         DTM_COPY -- Copy current frame to primary clipboard unit
  820.  
  821.     FUNCTION
  822.         DTM_COPY copies the current frame as an IFF ILBM frame to the
  823.         primary clipboard (unit 0).
  824.  
  825.         Starting with animation.datatype V41, this method creates a
  826.         temporary picture.datatype object, which will be fed with
  827.         bitmap, colormap, DTA_ObjName, DTA_ObjAuthor, DTA_ObjAnnotation,
  828.         DTA_ObjCopyright, DTA_ObjVersion, ADTA_BitMapHeader, ADTA_ModeID,
  829.         ADTA_NumColors, ADTA_ColorRegisters, ADTA_CRegs. Then this
  830.         method is passes to the picture.datatype object.
  831.  
  832.         Before V41, animation.datatype used it's own clipboard saving code.
  833.  
  834.     RESULT
  835.         The return code from the picture.datatype object.
  836.  
  837.     NOTE
  838.  
  839.     SEE ALSO
  840.         picture.datatype/DTM_COPY
  841.  
  842. animation.datatype/DTM_FRAMEBOX               animation.datatype/DTM_FRAMEBOX
  843.  
  844.     NAME
  845.         DTM_FRAMEBOX -- Get/or set the object's environment
  846.  
  847.     FUNCTION
  848.         The DTM_FRAMEBOX method is used to set or get the object's
  849.         environment.
  850.  
  851.         The FRAMEF_SPECIFY flag defines the mode of this method.
  852.  
  853.         If FRAMEF_SPECIFY is not set the object returns it's preferred
  854.         (optimum) enviroment in dtf_FrameInfo (output).
  855.  
  856.         If FRAMEF_SPECIFY is set, the application tells the object
  857.         about it's destination environment (got from dtf_ContentsInfo);
  858.         animation.datatype does nothing here (NOP), but a subclass can use
  859.         this to select a matching dither mode or select the best-matching
  860.         stream (in multi-stream animations like MPEG-2).
  861.  
  862.     RESULT
  863.         Returns non-zero for success, 0 for failure (NOP).
  864.  
  865.     NOTE
  866.  
  867. animation.datatype/DTM_PRINT                     animation.datatype/DTM_PRINT
  868.  
  869.     NAME
  870.         DTM_PRINT -- Print current or specified frame to file.
  871.  
  872.     FUNCTION
  873.         DTM_PRINT prints the current or a specifed frame as an IFF ILBM
  874.         picture to the printer.
  875.  
  876.         Starting with animation.datatype V41, this method creates a
  877.         temporary picture.datatype object, which will be fed with
  878.         bitmap, colormap, DTA_ObjName, DTA_ObjAuthor, DTA_ObjAnnotation,
  879.         DTA_ObjCopyright, DTA_ObjVersion, ADTA_BitMapHeader, ADTA_ModeID,
  880.         ADTA_NumColors, ADTA_ColorRegisters, ADTA_CRegs. Then this
  881.         method is passes to the picture.datatype object.
  882.  
  883.         Before V41, animation.datatype used it's own printer code.
  884.  
  885.     TAGS
  886.         ADTA_Frame (ULONG) -- (V41) Timestamp of the frame to print.
  887.             Defaults to the current frame.
  888.  
  889.         DTA_RastPort, DTA_DestCols, DTA_DestRows and DTA_Special
  890.         are also recognised by the picture.datatype DTM_PRINT code.
  891.         See picture.datatype/DTM_PRINT or datatypesclass autodoc.
  892.  
  893.     RESULT
  894.         The return code from the picture.datatype object.
  895.  
  896.     BUGS
  897.         - DTA_SelectDomain is ignored in V41 (as the whole DTM_SELECT
  898.           code is not working yet).
  899.  
  900.     NOTE
  901.  
  902.     SEE ALSO
  903.         picture.datatype/DTM_PRINT
  904.  
  905. animation.datatype/DTM_PROCLAYOUT           animation.datatype/DTM_PROCLAYOUT
  906.  
  907.     NAME
  908.         DTM_PROCLAYOUT -- Layout an animation.datatype object on applications
  909.  
  910.                           process
  911.  
  912.     FUNCTION
  913.         <not written yet, sorry>
  914.  
  915.     RESULT
  916.  
  917.     NOTE
  918.  
  919. animation.datatype/DTM_REMOVEDTOBJECT   animation.datatype/DTM_REMOVEDTOBJECT
  920.  
  921.     NAME
  922.         DTM_REMOVEDTOBJECT -- Release all window/screen related resources
  923.  
  924.     FUNCTION
  925.         DTM_REMOVEDTOBJECT is used to remove a animation.datatype object
  926.         from screen context. The playback is stopped (using ADTM_STOP),
  927.         then all resouces allocated in the initial GM_LAYOUT are freed.
  928.         This includes shared or exclusive pens allocated, temporary bitmaps
  929.         etc.
  930.  
  931.         After all, the method is passed to superclass.
  932.  
  933.         After using this method, the object is removed from screen's context
  934.         and can be re-used in another screen.
  935.  
  936.     RESULT
  937.         Returns return value from superclass.
  938.  
  939.     NOTE
  940.         This method is normally invoked from within
  941.         datatypes.library/RemoveDTObject. Manual usage is only neccesary
  942.         where AddDTObject wasn't used (see embed.datatype for example).
  943.  
  944. animation.datatype/DTM_TRIGGER                 animation.datatype/DTM_TRIGGER
  945.  
  946.     NAME
  947.         DTM_TRIGGER -- Trigger an action
  948.  
  949.     FUNCTION
  950.         Trigger an asyncrounous (!) action on the object.
  951.  
  952.         Supported are:
  953.  
  954.         Label           | Command   | Function                | Parameters
  955.         ----------------+-----------+-------------------------+------------
  956.          "Pause"        | "PAUSE"   | STM_PAUSE               | STMD_VOID
  957.          "Play"         | "PLAY"    | STM_PLAY                | STMD_VOID
  958.          "Rewind",      | "REWIND"  | STM_REWIND              | STMD_VOID
  959.          "Fast Forward" | "FF"      | STM_FASTFORWARD         | STMD_VOID
  960.          "Stop"         | "STOP"    | STM_STOP                | STMD_VOID
  961.          "Locate"       | "LOCATE"  | STM_LOCATE              | STMD_ULONG
  962.  
  963.         - Pause
  964.           Pauses the current playback.
  965.           The control process simply does a ADTM_PAUSE here.
  966.  
  967.         - Play
  968.           Start playback
  969.  
  970.         - Rewind
  971.           Skips ADTA_FrameIncrement frames back
  972.  
  973.         - Fast Forward
  974.           Skips ADTA_FrameIncrement frames forward
  975.  
  976.         - Stop
  977.           Stops the current playback.
  978.           The control process simply does a ADTM_STOP here.
  979.  
  980.         - Locate
  981.           The given parameter (dtt_Data; treated as ULONG) is used as the
  982.           frame number (or timestamp) to locate (e.g. load and display this
  983.           frame). This is simmilar to ADTM_LOCATE (but this isn't done here
  984.           yet).
  985.  
  986.     RESULT
  987.         Returns non-zero for success,
  988.         0 for failure (and result2 set to the cause:
  989.         ERROR_NO_FREE_STORE          - no memory
  990.         DTERROR_COULDNT_SEND_MESSAGE - object not ready to send (should NOT
  991.                                        occur)
  992.         ERROR_ACTION_NOT_KNOWN       - unknown STM_#? type
  993.  
  994.     BUGS
  995.         - STM_LOCATE is not implemented trougth ADTM_LOCATE
  996.  
  997.         - The given STM_#? type is not checked if it is supported or not.
  998.  
  999.     NOTE
  1000.         - Once again: This method is asyncrounous. You cannot assume
  1001.           that the triggered action is started nor finished after
  1002.           DTM_TRIGGER returns.
  1003.  
  1004.         - Common usage is a button field or a menu item to let the user
  1005.           to some actions on the object.
  1006.  
  1007. animation.datatype/DTM_WRITE                     animation.datatype/DTM_WRITE
  1008.  
  1009.     NAME
  1010.         DTM_WRITE -- Copy current or specified frame to file.
  1011.  
  1012.     FUNCTION
  1013.         DTM_WRITE copies the current or a specifed frame as an IFF ILBM
  1014.         picture to the given filehandle.
  1015.  
  1016.         Starting with animation.datatype V41, this method creates a
  1017.         temporary picture.datatype object, which will be fed with
  1018.         bitmap, colormap, DTA_ObjName, DTA_ObjAuthor, DTA_ObjAnnotation,
  1019.         DTA_ObjCopyright, DTA_ObjVersion, ADTA_BitMapHeader, ADTA_ModeID,
  1020.         ADTA_NumColors, ADTA_ColorRegisters, ADTA_CRegs. Then this
  1021.         method is passes to the picture.datatype object.
  1022.  
  1023.         Before V41, animation.datatype used it's own saving code.
  1024.  
  1025.     TAGS
  1026.         ADTA_Frame (ULONG) -- (V41) Timestamp of the frame to save.
  1027.             Defaults to the current frame.
  1028.  
  1029.     RESULT
  1030.         The return code from the picture.datatype object.
  1031.  
  1032.     NOTE
  1033.         - Subclasses may implement ADTA_Frame, ADTA_Frames and
  1034.           ADTA_FrameIncrement for their own encoders.
  1035.  
  1036.     SEE ALSO
  1037.         picture.datatype/DTM_WRITE
  1038.  
  1039. animation.datatype/GM_GOACTIVE                 animation.datatype/GM_GOACTIVE
  1040.  
  1041.     NAME
  1042.         GM_GOACTIVE -- Activate an animation.datatype gadget
  1043.  
  1044.     FUNCTION
  1045.         The GM_GOACTIVE method is used to indicate to a gadget that it has
  1046.         become active. This method overrides the superclass.
  1047.  
  1048.         See also GM_HANDLEINPUT, because this method is exactly the the
  1049.         same except the following things:
  1050.  
  1051.         - If the gpInput message mouse position is over the tapedeck.gadget
  1052.           it will become the active member (unless it has GA_Disabled == TRUE
  1053.           set for any reason).
  1054.  
  1055.     RESULT
  1056.         See GM_HANDLEINPUT
  1057.  
  1058.     NOTE
  1059.  
  1060. animation.datatype/GM_GOINACTIVE             animation.datatype/GM_GOINACTIVE
  1061.  
  1062.     NAME
  1063.         GM_GOINACTIVE -- Decativate an animation.datatype object
  1064.  
  1065.     FUNCTION
  1066.         The GM_GOINACTIBE method is used to indicate that the
  1067.         animation.datatype gadget has become inactive. This method overrides
  1068.         the superclass.
  1069.  
  1070.         If the embedded tapdeck.gadget was active, this method
  1071.         will be passed to it.
  1072.  
  1073.     RESULT
  1074.         The return code from the superclass is returned.
  1075.  
  1076.     NOTE
  1077.  
  1078. animation.datatype/GM_HANDLEINPUT           animation.datatype/GM_HANDLEINPUT
  1079.  
  1080.     NAME
  1081.         GM_HANDLEINPUT -- Process gadget input events
  1082.  
  1083.     FUNCTION
  1084.         The GM_HANDLEINPUT method is used to handle te input events of an
  1085.         active animation.datatype gadget. This method overrides the 
  1086.         superclass.
  1087.  
  1088.         If there is an active member (currently only tapedeck.gadget),
  1089.         all messages are passed througth to it.
  1090.  
  1091.         If there is no tapedeck.gadget in the display (e.g. DTA_ControlPanel
  1092.         == FALSE) and the object is not playing, a mouse SELECTUP starts
  1093.         the playback. If the object is playing, a SELECTUP pauses the
  1094.         playback.
  1095.  
  1096.     RESULT
  1097.         Do not interpret the results here, due they're a result of private
  1098.         internal activity.
  1099.         A later version will define here valid values.
  1100.  
  1101.     NOTE
  1102.  
  1103. animation.datatype/GM_HELPTEST                 animation.datatype/GM_HELPTEST
  1104.  
  1105.     NAME
  1106.         GM_HELPTEST -- Test if object has been hit by a help request
  1107.  
  1108.     FUNCTION
  1109.         The GM_HELPTEST method is used to determine if the given mouse
  1110.         coordinates are within the help domain of the animation.datatype
  1111.         gadget.
  1112.         This method overrides the superclass.
  1113.  
  1114.         If the mouse position is over the embedded tapdeck.gadget, this
  1115.         method is passed to it.
  1116.  
  1117.     RESULT
  1118.         GMR_HELPHIT or the return value of the embedded tapedeck.gadget
  1119.  
  1120.     NOTE
  1121.  
  1122. animation.datatype/GM_HITTEST                   animation.datatype/GM_HITTEST
  1123.  
  1124.     NAME
  1125.         GM_HITTEST -- Test if object has been hit by mouse
  1126.  
  1127.     FUNCTION
  1128.         The GM_HITTEST method is used to determine if the given mouse
  1129.         coordinates are within the domain of the animation.datatype gadget.
  1130.         This method overrides the superclass.
  1131.  
  1132.         If the mouse position is over the embedded tapdeck.gadget, this
  1133.         method is passed to it.
  1134.  
  1135.     RESULT
  1136.         GMR_GADGETHIT or the return value of the embedded tapedeck.gadget
  1137.  
  1138.     NOTE
  1139.  
  1140. animation.datatype/GM_LAYOUT                     animation.datatype/GM_LAYOUT
  1141.  
  1142.     NAME
  1143.         GM_LAYOUT -- Layout an animation.datatype object
  1144.  
  1145.     FUNCTION
  1146.         <not written yet, sorry>
  1147.  
  1148.     RESULT
  1149.         Returns return value from superclass.
  1150.  
  1151.     NOTE
  1152.  
  1153. animation.datatype/GM_RENDER                     animation.datatype/GM_RENDER
  1154.  
  1155.     NAME
  1156.         GM_RENDER -- Render an animation.datatype gadget
  1157.  
  1158.     FUNCTION
  1159.         The GM_RENDER method is used to render an animation.datatype object
  1160.         with the current frame. This method is also passed to the embedded
  1161.         tapedeck.gadget if DTA_ControlPanel is TRUE and if there is enougth
  1162.         space to render it (currenty a domain height < 16 pixels causes the
  1163.         tapedeck.gadget not to be rendered)
  1164. .       This method overrides the superclass.
  1165.  
  1166.         If this is the first GM_RENDER/GREDRAW_REDRAW after the initial
  1167.         GM_LAYOUT and DTA_Immediate was set to TRUE, the playback is
  1168.         started here.
  1169.  
  1170.     RESULT
  1171.         This method returns 0.
  1172.  
  1173.     NOTE
  1174.  
  1175. animation.datatype/MAIN                               animation.datatype/MAIN
  1176.  
  1177.     INTRODUCTION
  1178.         animation.datatype is the datatypes base class for all animation
  1179.         and movie subclasses. It is responsible for remapping, sound,
  1180.         scronisation, creating the controls and misc. other things
  1181.  
  1182.     FEATURES
  1183.         - Supports now the full animation.datatype interface like defined
  1184.           in include31:datatypes/animationclass.h:
  1185.           - Supports palette-per-frame, e.g. each frame can have it's own
  1186.             palette.
  1187.  
  1188.           - Dynamic timing. A frame can have a variable duration until
  1189.             the next frame occurs.
  1190.  
  1191.         - Fully compatible to the original animation.datatype V40.7
  1192.  
  1193.         - Configurable througth a preferences file.
  1194.  
  1195.         - Includes a CPU blitter for planar screens. If enabled by the prefs
  1196.           file, animation.datatype uses a CPU blitter instead of the OS
  1197.           blitter.
  1198.  
  1199.         - CyberGFX compatible:
  1200.           - Now animation.datatype V41 can handle non-planar bitmaps, e.g.
  1201.             chunkypixel bitmaps, as input.
  1202.             (Currently they cannot be remapped, the bitmaps are displayed
  1203.             unchanged on the destination screen).
  1204.  
  1205.           - Supports HAM/EHB -> 24-bit remapping. (TEMPORARY DISABLED).
  1206.  
  1207.         - No skipping anymore. The aniation.datatype V41 introduces
  1208.           a new feature called "adaptive frame rate selection". Instead
  1209.           of skipping frames when they cannot be displayed in real-time,
  1210.           the FPS rate is now adapted to fit (e.g. the maximum available
  1211.           playback speed without skipping).
  1212.  
  1213.  
  1214.     REQUIREMENTS
  1215.         - You need at least Kick/WB 3.0.
  1216.  
  1217.         - "realtime.library", >= V39              - for timing
  1218.         - "gadgets/tapedeck.gadget" (any version) - for the controls
  1219.  
  1220.            You need "sound.datatype" >= V40 for sound support.
  1221.  
  1222.     USAGE
  1223.         Usage is very simply: If you  have loaded an animation, you can
  1224.         control the animation using the tapedeck gadget at the bottom:
  1225.         "<<" skips some frames back
  1226.         ">"  starts playing
  1227.         ">>" skips some frames forward.
  1228.         The slider part can be used to move manually to a specific
  1229.         postion in the animation/movie.
  1230.  
  1231.         Note that there is also a prefs-file where you can set various
  1232.         options. See "preferences" section for details.
  1233.  
  1234.     INSTALLATION
  1235.         After unpacking this archive:
  1236.         Because this version does not include an Installer script, you have
  1237.         to do the installation manually through the shell:
  1238.  
  1239.           - Unpack this archive and copy the "animation.datatype" to
  1240.             SYS:Classes/DataTypes/:
  1241.  
  1242.             Copy CLONE FROM "animation.datatype" TO
  1243.             "SYS:Classes/DataTypes/animation.datatype"
  1244.  
  1245.     AUTHOR
  1246.         If you want to blame me, report any bugs, or wants a new version
  1247.         send your letter to:
  1248.                         Roland Mainz
  1249.                         Hohenstaufenstraße 8
  1250.                         52388 Nörvenich
  1251.                         GERMANY
  1252.  
  1253.         Phone: (+49)(0)2426/901568
  1254.         Fax:   (+49)(0)2426/901569
  1255.  
  1256.         EMAIL is also available (if you want to send me attachments
  1257.         larger than 1MB (up to 5MB, more with my permission):
  1258.  
  1259.         GISBURN@w-specht.rhein-ruhr.de
  1260.  
  1261.         Up to December 1997 I'm reachable using this email address, too:
  1262.         Reinhold.A.Mainz@KBV.DE
  1263.  
  1264.         | Please put your name and address in your mails !
  1265.         | German mailers should add their phone numbers.
  1266.         | See BUGS section above when submitting bug reports.
  1267.  
  1268.         Sorry, but I can only look once a week for mails.
  1269.         If you don't hear something from me within three weeks, please
  1270.         send your mail again (but watch about new releases) (problems with
  1271.         this email port are caused by reconfigurations, hackers, network
  1272.         problems etc.).
  1273.  
  1274.         The  entire  "animation.datatype"  package  may  be  noncommercially
  1275.         redistributed, provided  that  the package  is always  distributed
  1276.         in it's complete  form (including it's documentation). A small
  1277.         copy fee  for media costs is okay but any kind of commercial
  1278.         distribution is strictly forbidden without my permission !
  1279.         Comments and suggestions how to improve this program are
  1280.         generally appreciated!
  1281.  
  1282.         Thanks to: See "--datasheed--/THANKS TO" section...
  1283.  
  1284. animation.datatype/ObtainAnimationEnginemation.datatype/ObtainAnimationEngine
  1285.  
  1286.     NAME
  1287.         ObtainAnimationEngine -- Obtain the pointer to the animation class.
  1288.  
  1289.     SYNOPSIS
  1290.         class = ObtainAnimationEngine();
  1291.         d0
  1292.  
  1293.         struct IClass *ObtainAnimationEngine( void );
  1294.  
  1295.     FUNCTION
  1296.         This function is used to obtain the pointer to the class
  1297.         structure for this public BOOPSI class.
  1298.  
  1299.     RETURNS
  1300.         Returns a pointer to a valid public BOOPSI class pointer.
  1301.  
  1302.     NOTE
  1303.         - This function is also known as ObtainEngine. See
  1304.           "include31:clib/dtclass_protos.h"
  1305.  
  1306.         - Starting with V41, animation.datatype has a struct ClassLibrary
  1307.           structure (see V42 "include:intuition/classes.h") in it's
  1308.           classbase, where the BOOPSI class pointer can be obtained from.
  1309.           This method should be prefereed over ObtainAnimationEngine.
  1310.  
  1311. animation.datatype/OM_DISPOSE                   animation.datatype/OM_DISPOSE
  1312.  
  1313.     NAME
  1314.         OM_DISPOSE -- Dispose aniation.datatype class instance
  1315.  
  1316.     FUNCTION
  1317.         This method disposed all animation.datatype instance related
  1318.         rousources, including the tapedeck.gadget, the player etc.
  1319.  
  1320.     RESULT
  1321.         Returns the return value of the superclass.
  1322.  
  1323.     NOTE
  1324.  
  1325. animation.datatype/OM_GET                           animation.datatype/OM_GET
  1326.  
  1327.     NAME
  1328.         OM_GET -- Get the value of an attribute
  1329.  
  1330.     FUNCTION
  1331.         The OM_GET method is used to get a value of an attribute.
  1332.  
  1333.         <not fully written yet, sorry>
  1334.  
  1335.         ADTA_DestFrame (struct BitMap *) (V41) -- current remapped frame
  1336.             (the matching palette can be found in ADTA_GRegs).
  1337.             Note that reading this attribute is only save when the object
  1338.             is NOT playing.
  1339.  
  1340.         ADTA_Sample (UBYTE *) (V41) -- current frame's sample.
  1341.             Note that reading this attribute is only save when the object
  1342.             is NOT playing.
  1343.  
  1344.         ADTA_SampleLength (ULONG) (V41) -- current frame's sample length.
  1345.             Note that reading this attribute is only save when the object
  1346.             is NOT playing.
  1347.  
  1348.         ADTA_Period (ULONG) (V41) -- current frame's sample period.
  1349.             Note that reading this attribute is only save when the object
  1350.             is NOT playing.
  1351.  
  1352.         ADTA_Volume (ULONG) (V41) -- global volume.
  1353.  
  1354.         ADTA_Cycles (ULONG (V41) -- fixed to 1
  1355.  
  1356.     RESULT
  1357.         Returns non-zero on success, 0 on failure (attribute not recognized
  1358.         by OM_GET).
  1359.  
  1360.     NOTE
  1361.  
  1362. animation.datatype/OM_NEW                           animation.datatype/OM_NEW
  1363.  
  1364.     NAME
  1365.         OM_NEW -- Create a new animation.datatype object
  1366.  
  1367.     FUNCTION
  1368.         The OM_NEW method is used to create an instance of the
  1369.         animation.datatype class. This method is passed to the superclass
  1370.         first. After this, it sets up the instance data, creates sound
  1371.         and tapedeck objects, and the load and display processes. After
  1372.         all, when the object and the embedded objects and threads are
  1373.         ready for action, this method returns.
  1374.  
  1375.         On error this method calls OM_DISPOSE for it's own instance
  1376.         (e.g. CoerceMethod( cl, (Object *)retval, OM_DISPOSE );) and
  1377.         returns an error code.
  1378.  
  1379.     RESULT
  1380.         On success, a ptr to the object is returned,
  1381.         on failure, 0UL is returned, Result2 (IoErr()) contains the
  1382.         cause.
  1383.  
  1384.     NOTE
  1385.  
  1386. animation.datatype/OM_SET                           animation.datatype/OM_SET
  1387.  
  1388.     NAME
  1389.         OM_SET -- Set the attributes of a animation.datatype object
  1390.  
  1391.     FUNCTION
  1392.         The OM_SET method is used to set the attributes of a
  1393.         animation.datatype gadget. This method is passed to the superclass
  1394.         first.
  1395.  
  1396.     TAGS
  1397.         <not complety written yet, sorry>
  1398.  
  1399.         DTA_TopVert (LONG) -- Used to specify the vertical top image
  1400.             position. The value is stored in
  1401.             struct DTSpecialInfo -> si_TopVert. Values < 0 are set to 0.
  1402.             Setting this value causes that the object returns non-zero
  1403.             for OM_SET/OM_UPDATE, which should trigger an GM_RENDER with
  1404.             GREDRAW_UPDATE (the topmost instance is responsible for doing
  1405.             this).
  1406.             This overrides superclass's functionality.
  1407.  
  1408.         DTA_TopHoriz (LONG) -- Used to specify the horizontal top image
  1409.             position. The value is stored in
  1410.             struct DTSpecialInfo -> si_TopHoriz. Values < 0 are set to 0.
  1411.             Setting this value causes that the object returns non-zero
  1412.             for OM_SET/OM_UPDATE, which should trigger an GM_RENDER with
  1413.             GREDRAW_UPDATE (the topmost instance is responsible for doing
  1414.             this).
  1415.             This overrides superclass's functionality.
  1416.  
  1417.     RESULT
  1418.         Non-zero if a GM_RENDER with GREDRAW_UPDATE should be triggered
  1419.         by the topmost class.
  1420.  
  1421.     NOTE
  1422.  
  1423.     SEE ALSO
  1424.         OM_UPDATE, OM_NEW
  1425.  
  1426. animation.datatype/OM_UPDATE                     animation.datatype/OM_UPDATE
  1427.  
  1428.     NAME
  1429.         OM_UPDATE -- Update attributes
  1430.  
  1431.     FUNCTION
  1432.         OM_UPDATE updates anmation.datatype attributes, see OM_SET for
  1433.         details.
  1434.  
  1435.     TAGS
  1436.         See OM_SET autodoc.
  1437.  
  1438.     RESULT
  1439.  
  1440.     NOTE
  1441.  
  1442.     SEE ALSO
  1443.         OM_SET, OM_NEW
  1444.  
  1445. animation.datatype/preferences                 animation.datatype/preferences
  1446.  
  1447.    NAME
  1448.        preferences
  1449.  
  1450.    DESCRIPTION
  1451.        The "ENV:Classes/DataTypes/animation.prefs" file contains global
  1452.        settings for the animation datatype.
  1453.        The preferences file is an ASCII file containing one line where the
  1454.        preferences can be set.
  1455.        It can be superset by a local variable with the same name.
  1456.  
  1457.        Each line can contain settings, special settings for some subclasses
  1458.        can be set using the MATCHCLASS option.
  1459.        Lines beginning with a '#' or ';' chars are treated as comments.
  1460.        Lines are limitted to 256 chars.
  1461.  
  1462.    TEMPLATE
  1463.        MATCHCLASS/K,VERBOSE/S,ADAPTIVEFPS/S,NOADAPTIVEFPS/S,
  1464.        NUMPREFETCHFRAMES/K/N,WAITBOVP/S,NOWAITBOVP/S,OSBLITTER/S,
  1465.        CPUBLITTER/S,CHOOSEBLITTER/S,HACKS/S,NOHACKS/S
  1466.  
  1467.        MATCHCLASS -- Public class name. If given, the current prefs line
  1468.            is only for this subclass only.
  1469.            Example: MATCHCLASS="cdxl.datatype"
  1470.  
  1471.        VERBOSE -- Print information about the animation.
  1472.  
  1473.        ADAPTIVEFPS -- If set, the animation.datatype recalculates the
  1474.            playback rate that all frames and sounds can be displayed without
  1475.            skipping.
  1476.            This option is on per default starting with animation.datatype V41
  1477.  
  1478.        NOADAPTIVEFPS -- Turns the ADAPTIVEFPS flag off.
  1479.  
  1480.        NUMPREFETCHFRAMES -- Increases the number of frams which should
  1481.            be pre-fetched by the load process.
  1482.            Note: Increasing this value may cause the animation to run more
  1483.            smoothly, but takes also more memory.
  1484.            Defaults to 10.
  1485.  
  1486.        WAITBOVP -- Wait until raster beam reaches the bottom of the current
  1487.            viewport (screen). Only useful with some Gfx-Card-Software
  1488.            or graphics.library > V40.
  1489.            (In the future this option should be enabled if CyberGFX >= V41
  1490.            is detected).
  1491.  
  1492.        NOWAITBOVP -- Turns WAITBOVP flag off.
  1493.  
  1494.        OSBLITTER -- Use OS blitter even on planar screens. It is
  1495.            mutually exclusive to CPUBLITTER and CHOOSEBLITTER options.
  1496.            This option is off per default.
  1497.  
  1498.        CPUBLITTER - Use CPU blitter on planar screens. It is
  1499.            mutually exclusive to OSBLITTER and CHOOSEBLITTER options.
  1500.            This option is off per default.
  1501.  
  1502.        CHOOSEBLITTER -- If destination is a planar screen, the datatype
  1503.            makes a speed comparisation whether CPU or OS blitter is faster.
  1504.            It is mutually exclusive to OSBLITTER and CPUBLITTER options.
  1505.            This optoin is on per default.
  1506.  
  1507.        HACKS -- Use some internal hacks (system-conform, but I don't
  1508.            like them).
  1509.            This option is on per default.
  1510.  
  1511.        NOHACKS -- Turns HACKS option off.
  1512.  
  1513.    NOTE
  1514.        An invalid prefs file line will be ignored and forces the VERBOSE
  1515.        output.
  1516.  
  1517.    BUGS
  1518.        - Low memory may cause that the prefs file won't be parsed.
  1519.  
  1520.        - Lines are limitted to 256 chars
  1521.  
  1522.        - An invalid prefs file line will be ignored.
  1523.  
  1524.        - The sample path length is limitted to 200 chars. A larger
  1525.          value may crash the machine if an error occurs.
  1526.  
  1527.