home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / datatypes / mpegsystem_datatype / mpegsystem.datatype.doc < prev    next >
Encoding:
Text File  |  1998-06-01  |  18.3 KB  |  496 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpegsystem.datatype/--datasheed--
  4. mpegsystem.datatype/--input_format--
  5. mpegsystem.datatype/ADTM_LOADFRAME
  6. mpegsystem.datatype/ADTM_UNLOADFRAME
  7. mpegsystem.datatype/DTM_WRITE
  8. mpegsystem.datatype/MAIN
  9. mpegsystem.datatype/OM_DISPOSE
  10. mpegsystem.datatype/OM_NEW
  11. mpegsystem.datatype/preferences
  12. mpegsystem.datatype/--datasheed--           mpegsystem.datatype/--datasheed--
  13.  
  14.    NAME
  15.        mpegsystem.datatype -- data type for MPEG System streams
  16.  
  17.    SUPERCLASS
  18.        animation.datatype
  19.  
  20.    DESCRIPTION
  21.        The anim datatype, a sub-class of the animation.datatype, is used to
  22.        load and play MPEG System movies.
  23.  
  24.    METHODS
  25.        OM_NEW -- Create a new animation object from a description file. The
  26.            source may only be a file.
  27.  
  28.        OM_DISPOSE -- Dispose instance and contents (embedded objects etc.
  29.            etc.), then pass msg to superclass
  30.  
  31.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  32.            method will be executed like OM_SET downstairs.
  33.  
  34.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  35.            superclass was != 0UL.
  36.  
  37.        DTM_WRITE -- Save object's contents in local (MPEG System) or
  38.            superclass (IFF ILBM) format.
  39.            NOT IMPLEMENTED YET
  40.  
  41.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  42.            from embedded objects like bitmap, colormap and sample.
  43.  
  44.        ADTM_UNLOADFRAME -- Free resources obtained by ADTM_UNLOADFRAME.
  45.            The method is passed to the embedded objects.
  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.  
  53.    BUGS
  54.        - Support for streams with multiple video- and/or audio-streams
  55.          has been removed. The datatype uses currently evertimes
  56.          the first video- and the first audio-stream it finds.
  57.  
  58.        - ADTM_START, ADT_PAUSE, ADTM_STOP and ADTM_LOCATE are not passed
  59.          to the embedded mpevideo.datatype object(s), which may cause
  60.          speed loss if this datatype does speed optimisations based on use
  61.          of those methods.
  62.  
  63.        - The sound may be out-of-sync in the case that a stream
  64.          is very long (more than 60 minutes) due rounding problems.
  65.          (In theory it should not occur - and I did not see the bug...).
  66.  
  67.    TODO
  68.        - Fixing the bugs above.
  69.  
  70.        - Write the "--input_format--"-Autodoc section.
  71.  
  72.        - Leading zeros in the beginning of the file except the "start code"
  73.          begin sequence causes a stream not to be recognized by
  74.          datatypes.library.
  75.          May happen if someone reads raw data from a VideoCD.
  76.  
  77.        - Writing the encoder part, using mpegvideo.datatype V2's encoder
  78.          and mpegaudio.datatype's encoder parts.
  79.  
  80.          Coming soon... :-)
  81.  
  82.        - Implementation of ACTION_INFO in the internal filesystem that
  83.          (in theory) optimized reading using async I/O gets correct
  84.          parameters.
  85.  
  86.        - Support for MPEG 2 system streams.
  87.  
  88.        - QUICKSCAN option for optimized and much faster scanning of system
  89.          streams.
  90.  
  91.    HISTORY
  92.        V1.1
  93.          First public release.
  94.  
  95.        V1.2
  96.          - Fixed the descriptor (e.g. the file "MPEG System"). The
  97.            old one contains unneccesary data in the comparisation mask.
  98.            Now the descriptor matches the standard, except that
  99.            leading zero bytes (0x00) causes that the stream won't be
  100.            identified.
  101.            Thanks to Steve Cutting (stevejc@c031aone.net.au) for reporting
  102.            the bug.
  103.            Fixed.
  104.  
  105.          - Implemented IGNOREERRORS switch to get Steve Cutting's
  106.            (stevejc@c031aone.net.au) example file
  107.            "http://www.utexas.edustudents/cjso/Chabad/video/chase.mpg"
  108.            working.
  109.  
  110.          - Added missing VERBOSESYNTAX and DEBUG options to find problems
  111.            in the datatype without recompiling the complete source.
  112.  
  113.          - Fixed a bug in the FS:
  114.            The internal filesystem now returns ERROR_SEEK_ERROR of someone
  115.            send an ACTION_SEEK with an unknown position mode
  116.            (e.g. if it is none of OFFSET_(BEGINNING|CURRENT|END)).
  117.            Fixed.
  118.  
  119.          - Fixed some problems with the VERBOSE and DEBUG output (missing
  120.            newlines, single lines > 75 chars etc.).
  121.            Fixed.
  122.  
  123.        V1.3
  124.          - Minor code cleanup
  125.  
  126.          - Fixed and updated the autodoc.
  127.  
  128.          - Increased the handlers process priority up to 9
  129.            (normal FFS tasks are running at priority 10) to get more speed
  130.            during scanning.
  131.  
  132.        V1.4
  133.          - Added asyncio.library support code (but it does not work yet...).
  134.  
  135.          - Implemented ACTION_COPY_DIR_FH to get DupLockFromFH working which
  136.            is used in the new mpegaudio.datatype V2 (currently this feature
  137.            is not used because of some problems with mpega.library, but...).
  138.  
  139.          - Fixed a bug in OM_NEWs state machine which caused big problems
  140.            if an error occurs with IoErr() == 0.
  141.            Fixed.
  142.  
  143.        V1.5
  144.          - Removed non-working asyncio.library support code.
  145.  
  146.          - Implemented my own "async" dos packet system, which is more
  147.            efficient than asyncio.library's one (in our case !).
  148.  
  149.          - Added/removed/moved some code to get rid of a "Seek" in the 
  150.            scan phase.
  151.  
  152.          - Added some usefull comments.
  153.  
  154.          - Moved preferences support code into "prefs.c".
  155.  
  156.          - Implemented NOVERBOSE option as requested by many people.
  157.  
  158.          - Increased handlers priority to 15 and renamed the hander's
  159.            process.
  160.  
  161.    SEE ALSO
  162.        animation.datatype,
  163.        anim.datatype,
  164.        gifanim.datatype,
  165.        mpegvideo.datatype, mpegaudio.datatype,
  166.        picmovie.datatype,
  167.        cdxl.datatype, avi.datatype, quicktime.datatype,
  168.        moviesetter.datatype,
  169.        film.datatype,
  170.        directory.datatype,
  171.        markabletextdtclass
  172.  
  173. mpegsystem.datatype/--input_format--     mpegsystem.datatype/--input_format--
  174.  
  175.     NAME
  176.         MPEG System -- MPEG System stream format
  177.  
  178.     DESCRIPTION
  179.         <Not written yet, sorry>
  180.  
  181.     SEE ALSO
  182.  
  183. mpegsystem.datatype/ADTM_LOADFRAME         mpegsystem.datatype/ADTM_LOADFRAME
  184.  
  185.     NAME
  186.         ADTM_LOADFRAME -- Load frame
  187.  
  188.     FUNCTION
  189.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  190.         data of the animation.
  191.         The method is passed to the embedded mpegvideo.datatype object.
  192.         If successfull, the sample data of struct adtFrame are replaced
  193.         by the corresponsing audio data from the embedded 
  194.         mpegaudio.datatype object.
  195.  
  196.     RESULT
  197.         Returns the result from the embedded mpegvideo.datatype object
  198.         (including Result2).
  199.  
  200. mpegsystem.datatype/ADTM_UNLOADFRAME     mpegsystem.datatype/ADTM_UNLOADFRAME
  201.  
  202.     NAME
  203.         ADTM_UNLOADFRAME -- Unload frame contents
  204.  
  205.     FUNCTION
  206.         The ADTM_UNLOADFRAME method is used to release the contents of a
  207.         animation frame.
  208.  
  209.         This method is passed to the embedded mpegvideo.datatype object.
  210.  
  211.     RESULT
  212.         Returns the result from the embedded mpegvideo.datatype object.
  213.  
  214. mpegsystem.datatype/DTM_WRITE                   mpegsystem.datatype/DTM_WRITE
  215.  
  216.     NAME
  217.         DTM_WRITE -- Save data
  218.  
  219.     FUNCTION
  220.         This method saves the object's contents to disk.
  221.  
  222.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  223.         superclass, animation.datatype, which writes a single IFF ILBM
  224.         picture.
  225.  
  226.         If dtw_mode is DTWM_RAW, the object saved an MPEG System stream to
  227.         the filehandle given, starting with the current frame until
  228.         the end is reached.
  229.         The sequence saved can be controlled by the ADTA_Frame, ADTA_Frames
  230.         and ADTA_FrameIncrement attributes (see TAGS section below).
  231.  
  232.     TAGS
  233.         When writing the local ("raw") format, MPEG System movie, the
  234.         following attributes are recognized:
  235.  
  236.         ADTA_Frame (ULONG) - start frame, saving starts here.
  237.             Defaults to the current frame displayed.
  238.  
  239.         ADTA_Frames (ULONG) - the number of frames to be saved,
  240.             Defaults to (max_num_of_frames - curr_frame).
  241.  
  242.         ADTA_FrameIncrement (ULONG) - frame increment when saving.
  243.             Defaults to 1, which means: "jump to next frame".
  244.  
  245.     NOTE
  246.         This function is not implemented yet. A possible implementation 
  247.         would implement ACTION_WRITE in the virtial implementation and uses
  248.         mpegvideo.datatype and mpegaudio.datatype encoders...
  249.  
  250.     RESULT
  251.         Returns 0 for failure (IoErr() returns result2), non-zero
  252.         for success.
  253.  
  254. mpegsystem.datatype/MAIN                             mpegsystem.datatype/MAIN
  255.  
  256.     INTRODUCTION
  257.         Datatypes class for MPEG 1 System movies (including VideCD streams)
  258.  
  259.     REQUIREMENTS
  260.         - You need at least Kick/WB 3.0.
  261.  
  262.         - datatypes.library >= V45
  263.  
  264.         - "datatypes/animation.datatype", >= V40.
  265.           "animation.datatype 40.6 (28.09.93)" requires itself some
  266.           libraries/boopsi classes:
  267.           - "realtime.library", >= V39              - for timing
  268.           - "gadgets/tapedeck.gadget" (any version) - for the controls
  269.  
  270.         - mpegvideo.datatype >= V1.6 (V2.x preferred)
  271.  
  272.         - mpegaudio.datatype >= V1.1
  273.  
  274.     USAGE
  275.         If the datatypes descriptor file was activated, any attempt to load
  276.         a MPEG System stream using GMultiView, MultiView, AmigaGuide or
  277.         SwitchWindow will load and play the movie.
  278.  
  279.     INSTALLATION
  280.         After unpacking this archive:
  281.         Because this version does not include an Installer script, you have
  282.         to do the installation manually through the shell:
  283.  
  284.           - Unpack this archive and copy the "mpegsystem.datatype" to
  285.             SYS:Classes/DataTypes/:
  286.  
  287.         Copy CLONE FROM "mpegsystem.datatype" TO
  288.          "SYS:Classes/DataTypes/mpegsystem.datatype"
  289.  
  290.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  291.             directory.
  292.             If the descriptor already exists, you should not replace it,
  293.             otherwise you may loose "toolnodes" and other settings stored in
  294.             the existing descriptor.
  295.  
  296.      Copy CLONE FROM "MPEG System(%|.info)" TO DEVS:Datatypes/
  297.  
  298.     SOURCE
  299.         Source is included as an example how to write a datatypes clas
  300.         implements a virtual filesystem and embeds other datatype objects
  301.         for it's work.
  302.  
  303.     MODEL
  304.         This datatype uses a very complex model for decoding MPEG system
  305.         streams. The small drawing below shows the model (OK, the
  306.         drawing is not very good, it's incomplete and so on. If someone
  307.         has the time to draw a better one, send it to me).
  308.  
  309.                            system stream
  310.                                  |
  311.                                  |
  312.                                  Y
  313.              +-------------------------------------------------------------+
  314.              |            mpeg system datatype                             |
  315.              +-----------------------------------------+-------------------+
  316.              |              demultiplexer              | ADTM_LOADFRAME    |
  317.              |  video 0...video n | audio 0... audio n | ADTM_UNLOADFRAME  |
  318.              +-----+-------+------+------+-------+-----+-------------------+
  319.                    |       |             |       |               ^ ^
  320.                    |       |             |       |               | |
  321.                    |       *             |       *               | |
  322.                    |                     |                       | |
  323.                    |                     |                       | |
  324.                    Y                     Y                       | |
  325.       +---------------------+   +---------------------+          | |
  326.       | mpeg video datatype |   | mpeg audio datatype |          | |
  327.       +-----------+---------+   +--------+------------+          | |
  328.                   |                      |                       | |
  329.                   |                      |                       | |
  330.                   |                      +-----------------------+ |
  331.                   +------------------------------------------------+
  332.  
  333.     AUTHOR
  334.         If you want to blame me, report any bugs, or wants a new version
  335.         send your letter to:
  336.                         Roland Mainz
  337.                         Hohenstaufenstraße 8
  338.                         52388 Nörvenich
  339.                         GERMANY
  340.  
  341.         Phone: (+49)(0)2426/901568
  342.         Fax:   (+49)(0)2426/901569
  343.  
  344.         EMAIL is also available (if you want to send me attachments
  345.         larger than 1MB (up to 5MB, more with my permission):
  346.  
  347.         GISBURN@w-specht.rhein-ruhr.de
  348.  
  349.         Up to August 1998 I'm reachable using this email address, too:
  350.         Reinhold.A.Mainz@KBV.DE
  351.  
  352.         | Please put your name and address in your mails !
  353.         | German mailers should add their phone numbers.
  354.         | See BUGS section above when submitting bug reports.
  355.  
  356.         Sorry, but I can only look once a week for mails.
  357.         If you don't hear something from me within three weeks, please
  358.         send your mail again (but watch about new releases) (problems with
  359.         this email port are caused by reconfigurations, hackers, network
  360.         problems etc.).
  361.  
  362.         The  entire  "mpegsystem.datatype"  package  may  be  noncommercially
  363.         redistributed, provided  that  the package  is always  distributed
  364.         in it's complete  form (including it's documentation). A small
  365.         copy fee  for media costs is okay but any kind of commercial
  366.         distribution is strictly forbidden without my permission !
  367.         Comments and suggestions how to improve this program are
  368.         generally appreciated!
  369.  
  370.         Thanks to David Junod, who wrote the animation.datatype and lots of
  371.         the datatypes example code, Matt Dillon for his DICE,
  372.         Olaf 'Olsen' Barthel for his help, ideas and some text clips from
  373.         his documentations.
  374.  
  375. mpegsystem.datatype/OM_DISPOSE                 mpegsystem.datatype/OM_DISPOSE
  376.  
  377.     NAME
  378.         OM_DISPOSE -- Delete a mpegsystem.datatype object.
  379.  
  380.     FUNCTION
  381.         The OM_DISPOSE method is used to delete an instance of the
  382.         mpegsystem.datatype class. This method is passed to the superclass
  383.         when it has completed.
  384.  
  385.     RESULT
  386.         The object is deleted. 0UL is returned.
  387.  
  388. mpegsystem.datatype/OM_NEW                         mpegsystem.datatype/OM_NEW
  389.  
  390.     NAME
  391.         OM_NEW -- Create a mpegsystem.datatype object.
  392.  
  393.     FUNCTION
  394.         The OM_NEW method is used to create an instance of the
  395.         mpegsystem.datatype class.  This method is passed to the superclass
  396.         first. After this, mpegsystem.datatype parses the prefs file and 
  397.         makes a scan through the system stream to get index information 
  398.         about the single system stream packets.
  399.         After all, the mpegsystem.datatype starts two objects which reads
  400.         the single video and audio streams trougth an internal
  401.         "demultiplexer" (system stream splitter) filesystem.
  402.  
  403.         Subclasses of mpegsystem.datatype are not supported. Any attempt to
  404.         create a subclass object of mpegsystem.datatype will be rejected by
  405.         this method.
  406.  
  407.     ATTRIBUTES
  408.         The following attributes can be specified at creation time.
  409.  
  410.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  411.             attribute. Only DTST_FILE is supported.
  412.             If any other type was set in a given DTA_SourceType,
  413.             OM_NEW will be rejected.
  414.             Defaults to DTST_FILE.
  415.  
  416.         DTA_Handle -- For DTST_FILE, a BPTR filehandle is expected. This
  417.             handle will be created by datatypesclass depeding on the DTF_#?
  418.             flag, which is DTF_BINARY here.  DTST_FILE, datatypesclass
  419.             creates a file handle from the given DTA_Name and DTA_Handle
  420.             (a BPTR returned by Lock).
  421.             A DTST_RAM (create empty object) source type requires a NULL
  422.             handle.
  423.  
  424.     RESULT
  425.         If the object was created a pointer to the object is returned,
  426.         otherwise NULL is returned.
  427.  
  428. mpegsystem.datatype/preferences               mpegsystem.datatype/preferences
  429.  
  430.    NAME
  431.        preferences
  432.  
  433.    DESCRIPTION
  434.        The "ENV:Classes/DataTypes/mpegsystem.prefs" file contains global
  435.        settings for the datatype.
  436.        The preferences file is an ASCII file containing one line where the
  437.        preferences can be set.
  438.        It can be superset by a local variable with the same name.
  439.  
  440.        Each line can contain settings, special settings for some projects
  441.        can be set using the MATCHPROJECT option.
  442.        Lines beginning with a '#' or ';' chars are treated as comments.
  443.        Lines are limitted to 256 chars.
  444.  
  445.    TEMPLATE
  446.        MATCHPROJECT/K,VERBOSE/S,NOVERBOSE/S,VERBOSESYNTAX/S,
  447.        NOVERBOSESYNTAX/S,VERBOSEDEBUG=DEBUG/S,NOVERBOSEDEBUG=NODEBUG/S,
  448.        IGNOREERRORS/S,NOIGNOREERRORS/S
  449.  
  450.        MATCHPROJECT -- The settings in this line belongs only to this
  451.            project(s), e.g. if the case-insensitive pattern does not match,
  452.            this line is ignored.
  453.            The maximum length of the pattern is 128 chars.
  454.            Defaults to #?, which matches any project.
  455.  
  456.        VERBOSE -- Print information about the animation. Currently
  457.            the frame numbers and the used compression are printed, after all
  458.            number of scanned/loaded frames, set FPS rate, dimensions (width/
  459.            height/depth), sample information etc.
  460.  
  461.        NOVERBOSE -- Turns VERBOSE mode off.
  462.            Be _carefull_ with this options, this turns really ALL error 
  463.            messages OFF !
  464.  
  465.        VERBOSESYNTAX -- Print information about syntax errors
  466.  
  467.        NOVERBOSESYNTAX -- Turns the VERBOSESYNTAX option off.
  468.  
  469.        DEBUG
  470.        VERBOSEDEBUG -- Turns debugging mode on to get internal debugging
  471.            info without recompiling the whole source.
  472.  
  473.        NODEBUG
  474.        NOVERBOSEDEBUG -- Turns the DEBUG option off.
  475.  
  476.        IGNOREERRORS -- Ignores errors if system stream parsing fails;
  477.            the video+audio parts attempts to load the data until the
  478.            last scanned packet occurs.
  479.  
  480.        NOIGNOREERRORS -- Turns the IGNOREERRORS option off.
  481.  
  482.    NOTE
  483.        - An invalid prefs file line will be ignored and forces the VERBOSE
  484.          output.
  485.  
  486.    BUGS
  487.        - Low memory may cause that the prefs file won't be parsed.
  488.  
  489.        - Lines are limitted to 256 chars
  490.  
  491.        - An invalid prefs file line will be ignored.
  492.  
  493.        - The sample path length is limitted to 200 chars. A larger
  494.          value may crash the machine if an error occurs.
  495.  
  496.