home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 1 / Mecomp-CD.iso / amiga / datatypes / mpvdtc018 / mpegvideo.datatype.doc < prev   
Text File  |  1997-05-27  |  31KB  |  724 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpegvideo.datatype/--datasheed--
  4. mpegvideo.datatype/ADTM_LOADFRAME
  5. mpegvideo.datatype/DTM_FRAMEBOX
  6. mpegvideo.datatype/GM_LAYOUT
  7. mpegvideo.datatype/OM_DISPOSE
  8. mpegvideo.datatype/OM_NEW
  9. mpegvideo.datatype/preferences
  10. mpevideo.datatype/DTM_WRITE
  11. mpegvideo.datatype/--datasheed--             mpegvideo.datatype/--datasheed--
  12.  
  13.    NAME
  14.        mpegvideo.datatype -- data type for mpeg video streams
  15.  
  16.    SUPERCLASS
  17.        animation.datatype
  18.  
  19.    DESCRIPTION
  20.        The mpegvideo data type, a sub-class of the animation.datatype, is
  21.        used to load and play mpeg 1 video streams (Layer I).
  22.  
  23.    METHODS
  24.        OM_NEW -- Create a new animation object from a description file. The
  25.            source may only be a file.
  26.  
  27.        OM_DISPOSE -- Dispose instance and contents (frames, colormaps etc.),
  28.            then pass msg to superclass
  29.  
  30.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  31.            method will be executed like OM_SET downstairs.
  32.  
  33.        OM_SET -- Pass msg to superclass, and if the mpegvideo.datatype
  34.            instance is the "top instance", call GM_RENDER if retval from
  35.            superclass was != 0UL.
  36.  
  37.        GM_LAYOUT -- Collect information from superclass, set up
  38.            struct DTSpecialInfo and send an OM_NOTIFY containing usefull
  39.            attributes.
  40.  
  41.        DTM_FRAMEBOX -- Set up object for a specified environment if
  42.            FRAMEF_SPECIFY was set in (dtf -> dtf_FrameFlags).
  43.  
  44.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  45.            from internal FrameNode list like bitmap, colormap, samples, etc..
  46.  
  47.        All other methods are passed unchanged to superclass.
  48.  
  49.    ATTRIBUTES
  50.        Following attributes are set by the object and are READ-ONLY for
  51.        applications:
  52.        DTA_NominalHoriz        -- same as ADTA_Width
  53.        DTA_NominalVert         -- same as ADTA_Height
  54.        ADTA_Width              -- set by video stream
  55.        ADTA_Height             -- set by video stream
  56.        ADTA_Depth              -- set by video stream (or by prefs)
  57.        ADTA_NumColors          -- set by ADTA_Depth
  58.        ADTA_ColorRegisters     -- obj's palette with ADTA_NumColors entries
  59.        ADTA_CRegs              -- obj's palette with ADTA_NumColors entries
  60.        ADTA_Frames             -- total number of frames
  61.        ADTA_FramesPerSecond    -- set by video stream
  62.        ADTA_ModeID             -- calculated by BestModeID or set by prefs
  63.        ADTA_Remap              -- set by prefs file (if the destination
  64.                                   screen matches the requirements)
  65.        ADTA_KeyFrame           -- key frame
  66.        ADTA_Sample             -- sample (optional, if a sample is attached)
  67.        ADTA_SampleLength       -- sample length (optional, see ADTA_Sample)
  68.        ADTA_Period             -- sample period (optional, see ADTA_Sample)
  69.        ADTA_Volume             -- sample volume (optional, see ADTA_Sample)
  70.        ADTA_Cycles             -- sample cycle  (optional, see ADTA_Sample)
  71.  
  72.    BUGS
  73.        ALPHA preview version !!
  74.  
  75.        - If the mpeg video stream is not 100% standart conform,
  76.          the decoder part of this datatype will CRASH your machine.
  77.          Innocent memory will be overwritten !!
  78.  
  79.        - If you don't have my "paranimdtcpatch" patch running,
  80.          animation.datatype (animation.datatype 40.7 (28.09.93)) subclasses
  81.          will suffer under timing problems when two or more
  82.          animation.datatype objetcs are playing. I've released a matching
  83.          patch, DON'T blame me for this bug. Any comments for this problem
  84.          should be related  to the "paranimdtcpatch" project.
  85.          "paranimdtcpatch" is available in the aminet ("util/dtype").
  86.  
  87.        - In large videos, the frames at the end will be played slower than
  88.          those at the beginning of the file. This is the result of the
  89.          sequential search internally used (only serious with more than 25000
  90.          frames (mc68030/50mhz)).
  91.          Will be fixed.
  92.  
  93.        - The DICECOLOR output is currently __slow__. I'll fix this problem.
  94.          Another problem is that the colormaps created by DICECOLOR are equal
  95.          to the global colormap (at colormap's creation time). The suggested
  96.          behaviour is that each frame has a new colormap (for hi-quality
  97.          color output).
  98.          Will be fixed.
  99.  
  100.        - vmm.library virtual memory support is ____EXPERIMENTAL____. I cannot
  101.          say that it's safe because I don't see animation.datatype's source
  102.          code. But currently, it works __FINE__.
  103.          (One exception: Enforcer hits may block the system (occured with
  104.          Apollo 2030 mc68030 board with SCSI and a file as swap area)).
  105.          If possible, report your working/non-working configuration.
  106.  
  107.        - The current releases contain __MUCH__ dead code (25%-30%). This is
  108.          caused by syntax checking etc. functions, the 24 bit dithering
  109.          functions etc. which are not visible/usable in the public versions.
  110.  
  111.    TODO
  112.        - better error handling (and error messages)
  113.  
  114.        - code cleanup
  115.  
  116.        - bug fixing
  117.  
  118.        - Writing an amigaguide document
  119.  
  120.        - HAM/EHB output
  121.  
  122.    HISTORY
  123.        V1.1
  124.          First (official) public release.
  125.  
  126.        V1.2
  127.          Major code cleanup. I decided to rebuild the whole project from
  128.          scratch instead of releasing my internal V1.8. The reason is that
  129.          many things coded in it wasn't done with the required care. Now
  130.          I try to fix this.
  131.  
  132.          - Sorry, but in the V1.1 release, I've forgotten the COPYRIGHT
  133.            notice. Because I don't have the original ones (my code was a
  134.            mergin of mpeg_play 1.X, 2.0, I've taken them from the
  135.            mpeg_play 2.0 distribution).
  136.  
  137.          - Implemented the NOPFRAMES and NOBFRAMES switch (for those people
  138.            who like it).
  139.  
  140.          - The loader now returns usefull return codes instead of failing
  141.            silently.
  142.  
  143.          - Decrased the default depth from 7 to 5 planes. This is a more
  144.            reliable default value for grayscale mpeg videos (screen or
  145.            window).
  146.  
  147.          - Implemented "DICECOLOR" and "ORDERED" dithering.
  148.            The options COLORERROR and DICESKIP are for fine-tuning
  149.            speed <--> color output.
  150.  
  151.          - Introduced MAXFRAME (maximum number of frame to load) and
  152.            SKIPFRAMES to allow loading of large videos.
  153.  
  154.          - MODEID option added (for those which don't like the default
  155.            settings).
  156.  
  157.          - The datatypes descriptor file was WRONG. Now it should be correct.
  158.            If not, send me a mail (and if possible, the sample file which
  159.            won't work (packed with LhA for compression and CHECKSUMMING).
  160.            (Later versions of the descriptor should use additional code
  161.            to check the data).
  162.  
  163.        V1.3
  164.          - COLOR output implemented.
  165.  
  166.          - DICECOLOR: Found a bug (?? very strange one ??) in my code which
  167.            avoids the usage of a frame palette. DICECOLOR was intended
  168.            to produce high-quality per frame color remapping instead using
  169.            a global anim palette. Broken (e.g. working, but after a frame is
  170.            finished, the color table isn't cleared for now...).
  171.  
  172.          - I found out that the most time is consumed by the WritePixelArray
  173.            and copy functions. Later versions should contain a custom
  174.            WritePixelArray replacement which should be able to write directly
  175.            into FAST-RAM instead of writing into CHIP-RAM and them do a copy
  176.            into FAST-RAM. This would save __MUCH__ time.
  177.  
  178.          - Silly mistake: A
  179.            SetIoErr( 0L ); len = FRead( ..., requested ); sequence returns
  180.            under various fs IoErr() == (-1L) or something else. The loader
  181.            then aborts with this error code. (The code worked with RAM: disk,
  182.            my VideoCD-fs ("white book" mode)) and AMICDROM, but wasn't tested
  183.            with FFS or something else).
  184.            The code now uses Read instead of FRead, checks for
  185.            (len != requested), and only if TRUE IoErr() will be checked for
  186.            any error.
  187.  
  188.          - Introduced BUFFER preferences option.
  189.  
  190.          - A CTRL-D signal send to the loading process now stops the load.
  191.            This feature was implemented in V1.2, but I forgot to write it
  192.            down here.
  193.  
  194.          - The autodoc now has a TOC (table of contents).
  195.  
  196.          - Support for Martin Apel's VMM (Virtual Memory Manager).
  197.            (USEVMM switch in prefs file). The bitmaps can now be in virtual
  198.            memory (the colormaps are traditional allocated by GetColorMap
  199.            and cannot be in virtual memory (not yet nor in the future !)).
  200.            The mpegvideo.datatype uses the vmm.library, this allows
  201.            virtual memory usage even if the vmm.prefs disables virtual memory
  202.            for all other tasks.
  203.            NOTE: VMM is Shareware !!
  204.  
  205.        V1.4
  206.          - vmm.library is now opened on demand (e.g. the USEVMM switch was
  207.            set in the prefs file) inside the OM_NEW method.
  208.            This fixes two problems:
  209.            First: vmm.library was opened even it wasn't used.
  210.            Second: OpenLibrary( "vmm.library", ... ) inside the LibInit
  211.            function caused various problems.
  212.            vmm.library will be closed by LibExpuge function.
  213.  
  214.          - Removed serial verbose output. Now, if the VERBOSE switch was set
  215.            in the prefs file, all verbose output will be printed to
  216.            "CON://///auto/wait/close/inactive".
  217.  
  218.          - Set the SC NOOPTIMIZERPEEPHOLE switch for mc68060 support:
  219.            phase5 said that SAS/C 6.56 has a small bug in the peephole
  220.            optimizer which may cause trouble with mc68060. The peephole
  221.            optimizer will be turned on again if I know more details (and
  222.            a workaround).
  223.  
  224.          - The product of LUM_RANGE * CR_RANGE * CB_RANGE was limited to
  225.            a maximum of 512.  LUM_RANGE, CR_RANGE, CB_RANGE can now have
  226.            any positive value up to 255. A value of 0 is treated as 1,
  227.            fixing the problem of a possible division by zero.
  228.  
  229.          - Found a bug in COLOR dithering, which causes quality loss and
  230.            color disorientation. Fixing this bug will take MUCH time.
  231.            Not fixed yet.
  232.  
  233.          - To match the "DataTypes proposal", changes have been made:
  234.            1. The location of the prefs file is now ENV:Classes/DataTypes/
  235.               mpegvideo.prefs instead of ENV:DataTypes/mpegvideo.prefs
  236.            2. Subclasses of mpegvideo.datatype are not supported. Any
  237.               attempt to create a subclass object of mpegvideo.datatype
  238.               will be rejected by mpegvideo.datatype.
  239.  
  240.          - Partial code cleanup. I've implemented partial support for
  241.            output depths up to 16 bits. Currently, I'm limited to a maximum
  242.            depth of 8 bitplanes (e.g. 256 colors) for two reasons:
  243.            First, the system WritePixelArray8 function handles only byte
  244.            width pen indexes, second, animation.datatype handles only a
  245.            bitmaps up to 8 planes. Future releases of animation.datatype may
  246.            handle deeper bitplanes. (Custom players like my DBufDTAnim which
  247.            are using their own display code are able to display deeper
  248.            bitmaps yet.)
  249.  
  250.          - Found out a little problem: When using VMM (swap file) with
  251.            Enforcer, enforcer hits may block your system (occured on a
  252.            A2000 Apollo 2030 mc68030 board).
  253.            Who knows an answer for this problem ?
  254.  
  255.        V1.5
  256.          Minor changes to support special compiled versions for 68020+,
  257.          fpu etc.
  258.  
  259.          - Implemented the IGNOREERRORS switch, which attempts to ignore any
  260.            error during loading.
  261.  
  262.          - Removed some dead code.
  263.  
  264.        V1.6
  265.          The datatypes supports now scaling and sound. Sound was implemented
  266.          for two reasons:
  267.          1. For those streams which are distributed with a matching sound
  268.             file.
  269.          2. I'm reworking mpegsystem.datatype (which can play system streams,
  270.             e.g. video with interleaved audio). The goal is to implement
  271.             mpegsystem.datatype as a subclass of mpegvideo.datatype. The
  272.             audio stream will be parsed using mpegaudio.datatype.
  273.          Note that mpegvideo.datatype is still a GID_ANIMATION type datatype.
  274.          The GID_#? idetifiers belongs to the source data, not the
  275.          modifications done by a datatype code (a mpeg 1 video stream does
  276.          not contain any audio information, the sound is attached later).
  277.  
  278.          - Implemented the WIDTH and HEIGHT options in the prefs file to
  279.            support scaling.
  280.  
  281.          - Implemented SAMPLE and VOLUME options to support sound.
  282.  
  283.          - Now uses BestModeID for selecting the screen mode of the
  284.            animation. The MODEID preference option overides this.
  285.            The old behavior was to set the ADTA_ModeID attribute only if the
  286.            MODEID prefs option was set, otherwise the default from
  287.            animation.datatype was taken (which was everytimes 0).
  288.  
  289.          - Fixed the FPS preference option. If it was set, the value was got
  290.            from the depth option instead using the given value.
  291.  
  292.          - Implemented a processing gauge as requested by Allan Odgaard
  293.            (Duff@DK-Online.DK) and many other people. The matching
  294.            NOPROGRESSGAUGE switch disables it. If the input filehandle is a
  295.            pipe, the gauge may not work properly.
  296.  
  297.          - Implemented a lowermem limit (MINTOTALMEM option) for those people
  298.            who wants to see at least the beginning of a big anim (idea by
  299.            Allan Odgaard (Duff@DK-Online.DK)).
  300.  
  301.          - Implemented multi-line preferences, supports comments and
  302.            per-project settings (MATCHPROJECT option). The old preference
  303.            files/vars are compatible.
  304.  
  305.          - The stack size for the OM_NEW method is now checked. If the
  306.            required size (curretly 12kb) isn't available, a requester will
  307.            notify the user and the method returns an error.
  308.  
  309.        V1.7
  310.          - Recompiled with SAS/C 6.57. Switched the peephole optimizer on
  311.            (see V1.4 bugs).
  312.  
  313.          - Rewrote the DICECOLOR dithering/remapping code. The DICECOLOR
  314.            color mode now creates a colormap per frame (animation.datatype
  315.            40.7 does not support these colormap changes per frame (it's
  316.            output looks like a color trash). Custom animation players which
  317.            uses animation.datatype subclasses for loading (like my
  318.            DBufDTAnim) don't have this problem. animation.datatype V41 will
  319.            support these colormaps-per-frame.
  320.  
  321.            I changed the algorithm from a single-pass into a multi-pass
  322.            operation, which allows the code to run on other output modes
  323.            like ORDERED or FS (Floyd-Steinberg). A side-effect of this
  324.            change is that options like COLORERROR and DICESKIP are selected
  325.            automatically, which is more user-friendly.
  326.  
  327.            If you want to get the old DICECOLOR output, use
  328.            DITHER=COLOR PALETTEPERFRAME options.
  329.  
  330.          - The mpegvideo.datatype uses 24 bit-colors internally and
  331.            writes 32 bits per (r,b,g) gun. Now the high order bits of each
  332.            color gun are replicated through the whole INT32.
  333.  
  334.          - Fixed a bug in the SAMPLE option, which caused possible crashes.
  335.  
  336.          - Fixed a bug in LibExpunge (didn't check lib_OpenCnt), which is
  337.            also present in all my other external BOOSI classes (and
  338.            datatypes).
  339.            Thanks to Guenter Niki (gniki@informatik.uni-rostok.de) for
  340.            reporting this bug.
  341.  
  342.          - Implemented the mpeg saveing code (mpeg encoder). Currently,
  343.            only mpeg-1 streams are written out.
  344.            (Will be enabled in the public versions ONLY upon request;
  345.            code is currently under construction).
  346.  
  347.          - Increased the stack requirements from 12kb up to 16kb, mainly
  348.            to allow more recursive operations.
  349.  
  350.          - Implemented random access to frames (e.g you need not to load
  351.            the whole animation, decodung is done on the fly).
  352.            (Will be enabled in the public versions ONLY upon request;
  353.            code is currently under construction,
  354.            the matching LOADALL switch it set everytimes).
  355.  
  356.        V1.8
  357.          - Added partial support for mpeg-2 (MPEG-2 does NOT work yet !),
  358.            both encoder+decoder.
  359.  
  360.          - Added my own WritePixelArray8 replacement, which operates
  361.            directly on the fast-mem bitmaps. This saves some internal
  362.            copies, chipmem buffer for WPA8 etc.
  363.  
  364.          - Added my own scaling routine, replacing
  365.            graphics.library/BitMapScale (which needs chipmem as temp.
  366.            buffer).
  367.            Does not work properly yet.
  368.  
  369.          - Fixed the gauge, which didn't work correctly with large streams
  370.            (>= 8MB).
  371.            Fixed.
  372.  
  373.          - The gauge ha now a text info, which shows the remaining time
  374.            to decode.
  375.  
  376.          - Added experimental stack swapping code. The "Need more stack"-
  377.            requester has been removed for this reason.
  378.  
  379.            This also fixes a possible deadlock of "input.device" because
  380.            the GM_LAYOUT method was running with low stack.
  381.            Fixed.
  382.  
  383.          - Color table setup now retries color table build with an increased
  384.            COLORERROR if table (set by LUM_RANGE * CR_RANGE * CB_RANGE) does
  385.            not fit. This allows any #?_RANGE value.
  386.  
  387.          - Fixed different problems within color setup. Now this should
  388.            work with a higher quality, and a little bit faster.
  389.  
  390.          - Fixed the descriptor, which din't match all mpeg video streams.
  391.            Fixed.
  392.  
  393.          - DTM_WRITE should return ERROR_NOT_IMPLEMENTED if DTWM_RAW mode is 
  394.            requested (becuase the encoder has been disabled, e.g. commented
  395.            out). Now this is correctly done.
  396.            Fixed.
  397.  
  398.          - The 06060-Version now checks for the AFF_68060 (1L<<7) execbase fl
  399. ag
  400.            instead using the AFF_68040.
  401.            Fixed.
  402.  
  403.          - Added QUALITY prefs option and matching float-dct code.
  404.  
  405.    NOTES
  406.  
  407.    SEE ALSO
  408.        animation.datatype,
  409.        mpegsystem.datatype, mpegvideo.datatype
  410.        picmovie.datatype,
  411.        directory.datatype,
  412.        markabletextdtclass,
  413.        paranimdtcpatch
  414.  
  415. mpegvideo.datatype/ADTM_LOADFRAME           mpegvideo.datatype/ADTM_LOADFRAME
  416.  
  417.     NAME
  418.         ADTM_LOADFRAME -- Load frame
  419.  
  420.     FUNCTION
  421.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  422.         data of the animation.
  423.         The given timestamp will be used to find the closest timestamp
  424.         in the internal FrameNode list. If it was found, the corresponding
  425.         timing, bitmap, colormap and sound data are stored into the struct
  426.         adtFrame,
  427.  
  428.     RESULT
  429.         Returns always non-zero.
  430.  
  431. mpegvideo.datatype/DTM_FRAMEBOX               mpegvideo.datatype/DTM_FRAMEBOX
  432.  
  433.     NAME
  434.         DTM_FRAMEBOX -- Set up object for a specified environment
  435.  
  436.     FUNCTION
  437.         The DTM_FRAMEBOX method is used to set up for a specified
  438.         environment. This method is passed to the superclass after
  439.         mpegvideo.datatype instance finished it's work.
  440.  
  441.         Only if FRAMEF_SPECIFY is set in (dtf -> dtf_FrameFlags), the
  442.         mpegvideo.datatype instance will modify the ADTA_Remap to FALSE if
  443.         the NOREMAP switch in the prefs file was set and the animation
  444.         depth matches the given (frameinfo -> fri_Dimensions . Depth) depth.
  445.  
  446.     RESULT
  447.         The value from the superclass is returned.
  448.  
  449.     SEE ALSO
  450.         3.1_Examples2:DataTypes/Src/ClipView/clipview.c
  451.  
  452. mpegvideo.datatype/GM_LAYOUT                     mpegvideo.datatype/GM_LAYOUT
  453.  
  454.    NAME
  455.        GM_LAYOUT -- Layout animation object
  456.  
  457.    FUNCTION
  458.        This method is passed to the superclass first.
  459.        Then it collects information from superclass, set up
  460.        struct DTSpecialInfo and send an OM_NOTIFY containing the following
  461.        attributes:
  462.        DTA_VisibleVert,   (DTA_Domain -> Height)
  463.        DTA_TotalVert,     (same as ADTA_Height)
  464.        DTA_NominalVert,   (same as ADTA_Height)
  465.        DTA_VertUnit,      1UL,
  466.        DTA_VisibleHoriz,  (DTA_Domain -> Width),
  467.        DTA_TotalHoriz,    (same as ADTA_Width),
  468.        DTA_NominalHoriz,  (same as ADTA_Width),
  469.        DTA_HorizUnit,     1UL,
  470.        GA_ID,             (GadgetID),
  471.        DTA_Title,         (same as DTA_Name),
  472.        DTA_Busy,          FALSE,
  473.        DTA_Sync,          TRUE
  474.  
  475.     RESULT
  476.         The value from the superclass is returned.
  477.  
  478. mpegvideo.datatype/OM_DISPOSE                   mpegvideo.datatype/OM_DISPOSE
  479.  
  480.     NAME
  481.         OM_DISPOSE -- Delete a mpegvideo.datatype object.
  482.  
  483.     FUNCTION
  484.         The OM_DISPOSE method is used to delete an instance of the
  485.         mpegvideo.datatype class.  This method is passed to the superclass
  486.         when it has completed.
  487.         This method frees all frame nodes and their contents (pictures, their
  488.         colormaps, sounds etc.).
  489.  
  490.     RESULT
  491.         The object is deleted. 0UL is returned.
  492.  
  493. mpegvideo.datatype/OM_NEW                           mpegvideo.datatype/OM_NEW
  494.  
  495.     NAME
  496.         OM_NEW -- Create a mpegvideo.datatype object.
  497.  
  498.     FUNCTION
  499.         The OM_NEW method is used to create an instance of the
  500.         mpegvideo.datatype class.  This method is passed to the superclass
  501.         first. After this, mpegvideo.datatype loads it's preference file
  502.         (and the sound file, if one was specified), parses the whole video
  503.         stream, putting pictures into memory.
  504.         Any fatal error aborts the load, non-serious errors are reported.
  505.  
  506.         Subclasses of mpegvideo.datatype are not supported. Any attempt to
  507.         create a subclass object of mpegvideo.datatype will be rejected
  508.         by this method.
  509.  
  510.     ATTRIBUTES
  511.         The following attributes can be specified at creation time.
  512.  
  513.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  514.             attribute. Currently, only a source type of DTST_FILE is
  515.             supported. If any other type was set in a given DTA_SourceType,
  516.             OM_NEW will be rejected with result2 == ERROR_OBJECT_WRONG_TYPE.
  517.             Defaults to DTST_FILE.
  518.  
  519.         DTA_Handle (BPTR) -- If DTA_SourceType is DTST_FILE, the given file
  520.             will be used as an mpeg video stream to read in.
  521.  
  522.     RESULT
  523.         If the object was created a pointer to the object is returned,
  524.         otherwise NULL is returned.
  525.  
  526. mpegvideo.datatype/preferences                 mpegvideo.datatype/preferences
  527.  
  528.    NAME
  529.        preferences
  530.  
  531.    DESCRIPTION
  532.        The "ENV:Classes/DataTypes/mpegvideo.prefs" file contains global
  533.        settings for the datatype.
  534.        The preferences file is an ASCII file containing one line where the
  535.        preferences can be set.
  536.        It can be superset by a local variable with the same name.
  537.  
  538.        Each line can contain settings, special settings for some projects
  539.        can be set using the MATCHPROJECT option.
  540.        Lines beginning with a '#' or ';' chars are treated as comments.
  541.        Lines are limitted to 256 chars.
  542.  
  543.    TEMPLATE
  544.        MATCHPROJECT/K,MODEID/K/N,WIDTH/K/N,HEIGHT/K/N,DEPTH/K/N,DITHER/K,
  545.        LUM_RANGE/K/N,CR_RANGE/K/N,CB_RANGE/K/N,COLORERROR/K/N,
  546.        PALETTEPERFRAME/S,NOREMAP/S,MAXFRAME/K/N,SKIPFRAMES/K/N,FPS/K/N,
  547.        NOPFRAMES/S,NOBFRAMES/S,SAMPLE/K,VOLUME/K/N,BUFFER/K/N,LOADALL/S,
  548.        USEVMM/S,MINTOTALMEM/K/N,IGNOREERRORS/S,VERBOSE/S,NOPROGRESSGAUGE/S,
  549.        QUALITY/S
  550.  
  551.        MATCHPROJECT -- The settings in this line belongs only to this
  552.            project(s), e.g. if the case-insensitive pattern does not match,
  553.            this line is ignored.
  554.            The maximum length of the pattern is 128 chars.
  555.            Defaults to #?, which matches any project.
  556.  
  557.        MODEID -- Select screen mode id of datatype (will be stored in
  558.            ADTA_ModeID). Note that the DOS ReadArgs function used for parsing
  559.            fetches a SIGNED long. The bit 31 will be represented by minus
  560.            '-'. (example: "MODEID=266240" sets the mode to the A2024 screen
  561.            mode id)
  562.            Defaults to 0, which means: Use the best screenmode available
  563.            for the given width, height and depth.
  564.  
  565.        WIDTH -- Set the animation's width. The video will be scaled to this
  566.            width.
  567.            Defaults to 0, which means: Use video's width.
  568.  
  569.        HEIGHT -- Set the animation's height. The video will be scaled to this
  570.            height.
  571.            Defaults to 0, which means: Use video's height.
  572.  
  573.        DEPTH -- depth for the selected scaling mode
  574.            A value describing the "depth" of the animation.
  575.            1 upto 8 are valid, under- or overflows will be truncated
  576.            to the maximum supported.
  577.            The default depth will be selected by the DITHER mode.
  578.  
  579.        DITHER -- dither type, one of
  580.            GRAY            -- grayscale output (default)
  581.            HAM             -- ham (ham4/ham6/ham8 etc.)            (n/a)
  582.            EHB             -- extra halfbright                     (n/a)
  583.            COLOR           -- color output
  584.            HYBRID          -- hybrid dither                        (n/a)
  585.            FS2             -- floyd-steinberg dithering            (n/a)
  586.            FS4             -- dito.                                (n/a)
  587.            ORDERED         -- ordered dither
  588.  
  589.            GRAY is the grayscale mode.
  590.  
  591.            HAM (hold-and-modify) mode:
  592.            not implemented yet
  593.  
  594.            EHB (extra halfbright mode):
  595.            not implemented yet
  596.  
  597.            COLOR remaps the frames into a fixed color space.
  598.  
  599.            Defaults to GRAY.
  600.  
  601.        LUM_RANGE -- sets the number of colors assigned to the luminance
  602.            component when dithering the image.  The product of LUM_RANGE,
  603.            CR_RANGE and CB_RANGE should be less than the number of colors
  604.            selected by the DEPTH option.
  605.            This will only affect ORDERED and COLOR dithering and the base
  606.            palette of the DICECOLOR remapping.
  607.            Any value between 1 upto 255 is allowed, 0 is treated as 1.
  608.            Defaults to 8.
  609.  
  610.        CR_RANGE -- sets the number of colors assigned to the red component of
  611.            the chrominace range when dithering the image.  The product of
  612.            LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of
  613.            colors selected by the DEPTH option.
  614.            This will only affect ORDERED and COLOR dithering and the base
  615.            palette of the DICECOLOR remapping.
  616.            Any value between 1 upto 255 is allowed, 0 is treated as 1.
  617.            Defaults to 4.
  618.  
  619.        CB_RANGE -- sets the number of colors assigned to the blue component
  620.            of the chrominace range when dithering the image.  The product of
  621.            LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of
  622.            colors selected by the DEPTH option.
  623.            This will only affect ORDERED and COLOR dithering and the base
  624.            palette of the DICECOLOR remapping.
  625.            Any value between 1 upto 255 is allowed, 0 is treated as 1.
  626.            Defaults to 4.
  627.  
  628.        COLORERROR -- Set the error range when allocating colors.
  629.            The error range is used for color matching
  630.            (like this: if( ABS( (pixel . red) - (colormap . red) ) +
  631.                        ABS( <dito. green> ) + ABS( <dito. blue> )
  632.                        < colorerror ) then use this color index).
  633.            A low value (0) means high quality remapping and slow remapping,
  634.            high values (50) means low quality (using less color indexes).
  635.            The value set here will also affect DICECOLOR remapping, because
  636.            the search algorithm is the same.
  637.            Defaults to 0.
  638.  
  639.        PALETTEPERFRAME -- Create a own palette for each frame.
  640.  
  641.        MAXFRAME -- Maximum number of frames to load.
  642.            Defaults to 0, which means: Load all frames.
  643.  
  644.        SKIPFRAMES -- Load only the n-th frame of an animation.
  645.            The internal timing (e.g. time code) is not affected, so
  646.            the FPS value will be correct.
  647.            Defaults to 0 which means: Skip no frame.
  648.  
  649.        FPS -- frames per second
  650.            Defaults to 0, which means: overtake fps rate from video stream.
  651.            Setting the FPS value also affects an attched sound. The period
  652.            of the sample (e.g. the playback speed) will everytimes as long
  653.            as the frame is displayed.
  654.  
  655.        NOPFRAMES -- ignore any type P frames (predicted frames) when loading.
  656.  
  657.        NOBFRAMES -- ignore any type B frames (bidirectional frames) when
  658.            loading.
  659.  
  660.        SAMPLE -- Attach the given sample to the animation. The sample will
  661.            be loaded using datatypes (GID_SOUND).
  662.            Only one sample can be attached to one video stream, any following
  663.            attempt to attach the sample will be ignored.
  664.  
  665.        VOLUME -- Volume of the sound when playing.
  666.            Defaults to 64, which is the maximum. A value greater than 64 will
  667.            be set to 64.
  668.  
  669.        BUFFER -- read buffers size. Minimum is 2048, lower values are set to
  670.            2048.
  671.            Defaults to 2048.
  672.  
  673.        LOADALL -- load all frames before displaying it. Currently
  674.            everytimes set.
  675.  
  676.        USEVMM -- Use Martin Apel's vmm.library for bitmaps
  677.            (experimental, but works __fine__).
  678.  
  679.        MINTOTALMEM -- Minimum total memory available. If less memory
  680.           available, abort loading.
  681.           Defaults to 0, which means: Don't use this option.
  682.  
  683.        IGNOREERRORS -- Ignore errors while parsing/decoding etc.
  684.  
  685.        VERBOSE -- Verbose output. Prints out current frame etc., some
  686.            statistical information and maybe, debugging infos.
  687.            Verbose output will be printed in a console window
  688.            ("CON://///auto/wait/close/inactive/MPEG Video DataType").
  689.  
  690.        NOPROGRESSGAUGE -- Disables the progress gauge which is displayed
  691.            during loading of the mpeg stream.
  692.  
  693.        QUALITY -- If set, mpegvideo.datatype uses floating-point dct
  694.            decoding, which results in a better output quality.
  695.  
  696.    NOTE
  697.        An invalid prefs file line will force the default settings for this
  698.        line and the VERBOSE option.
  699.  
  700.    BUGS
  701.        - Low memory may cause that the prefs file won't be parsed.
  702.  
  703.        - Lines are limitted to 256 chars
  704.  
  705. mpevideo.datatype/DTM_WRITE                       mpevideo.datatype/DTM_WRITE
  706.  
  707.     NAME
  708.         DTM_WRITE -- Save data
  709.  
  710.     FUNCTION
  711.         This method saves the object's contents to disk.
  712.  
  713.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  714.         superclass, animation.datatype, which writes a single IFF ILBM
  715.         picture.
  716.         The local data format (e.g. dtw_Mode == DTWM_RAW) is currently
  717.         not supported, this method returns 0UL
  718.         (and result2 == ERROR_NOT_IMPLEMENTED) in that case.
  719.  
  720.     RESULT
  721.         Returns 0 for failure (IoErr() returns result2), non-zero
  722.         for success.
  723.  
  724.