home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / datatypes / mpegaudio_datatype / mpegaudio.datatype.doc < prev    next >
Encoding:
Text File  |  1998-06-01  |  9.0 KB  |  267 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpegaudio.datatype/--datasheed--
  4. mpegaudio.datatype/--input_format--
  5. mpegaudio.datatype/DTM_WRITE
  6. mpegaudio.datatype/MAIN
  7. mpegaudio.datatype/OM_DISPOSE
  8. mpegaudio.datatype/OM_NEW
  9. mpegaudio.datatype/--datasheed--             mpegaudio.datatype/--datasheed--
  10.  
  11.    NAME
  12.        mpegaudio.datatype -- data type for MPEG audio streams
  13.  
  14.    SUPERCLASS
  15.        sound.datatype
  16.  
  17.    DESCRIPTION
  18.        The mpegaudio.datatype, a sub-class of the sound.datatype, is
  19.        used to load and save MPEG audio streams using "maplay" / "mpega"
  20.        and the 8SVX/AIFF datatype.
  21.  
  22.    METHODS
  23.        OM_NEW -- Create a new sound object from a description file. The
  24.            source may only be a file. An empty object (DTST_RAM) can
  25.            also be created (unless the project was compiled with
  26.            the NO_ENCODER flag).
  27.  
  28.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  29.            method will be executed like OM_SET downstairs.
  30.  
  31.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  32.            superclass was != 0UL.
  33.  
  34.        DTM_WRITE -- Save data in local (MPEG audio) or superclass (IFF 8SVX)
  35.            format.
  36.            Local format has not been implemented yet.
  37.  
  38.        All other methods are passed unchanged to superclass.
  39.  
  40.    ATTRIBUTES
  41.        Following attributes are set by the object and are READ-ONLY for
  42.        applications (if the datatype is used for saving (e.g. the
  43.        application creates an empty mpegaudio.datatype object and fills
  44.        in some required atrributes as shown in the "DTConvert" example),
  45.        these attributes are used by the encoder to create a MPEG audio
  46.        sound file):
  47.  
  48.        DTA_ObjName         -- Set by DTA_Name's value.
  49.        SDTA_VoiceHeader    -- Copy from the embedded 8svx/aiff.datatype 
  50.                               object
  51.        SDTA_Sample         -- 8 bit sample data
  52.        SDTA_SampleLength   -- length of 8 bit sample data
  53.        SDTA_Volume         -- volume (got from the voiceheader)
  54.        SDTA_Period         -- created from (VoiceHeader -> vh_SamplesPerSec)
  55.                               and system's clock
  56.  
  57.    BUGS
  58.        The project has been not very well tested yet. Therefore...
  59.        ... no known bugs.
  60.  
  61.    TODO
  62.        - Fixing the bugs above
  63.  
  64.        - Support for SDTM_LOADFRAME / SDTM_UNLOADFRAME (implies also support
  65.          for 16-bit audio á la RTA /  AHI).
  66.  
  67.        - Encoder support (e.g. DTM_WRITE).
  68.  
  69.    HISTORY
  70.        V1.1
  71.          First public release.
  72.  
  73.        V1.2
  74.          - Swichted to Stephane Tavenard's "mpega".
  75.            (Have gave me the tip how to get in sync with the video (using
  76.            the options -b 1 -t 0).
  77.            Thank you very much Stephane !
  78.  
  79.          - Small code cleanup (the class dispatcher is now a static
  80.            function etc.)
  81.  
  82.        V2.1
  83.          - Swichted to Stephane Tavenard's "mpega.library".
  84.            Thank you very much Stephane !
  85.  
  86.        V2.2
  87.          - Now stero files are decoded with both left+right channel instead
  88.            the left channel only.
  89.  
  90.          - Reduced the decoder's buffer size from 2048 down to 1024 bytes
  91.            to get a much more accurate lip sync if used within
  92.            mpegsystem.datatype (for tests only...).
  93.  
  94.    SEE ALSO
  95.        sound.datatype
  96.  
  97. mpegaudio.datatype/--input_format--       mpegaudio.datatype/--input_format--
  98.  
  99.     NAME
  100.         MPEG audio --
  101.  
  102.     DESCRIPTION
  103.         <not written yet>
  104.  
  105.     SEE ALSO
  106.  
  107. mpegaudio.datatype/DTM_WRITE                     mpegaudio.datatype/DTM_WRITE
  108.  
  109.     NAME
  110.         DTM_WRITE -- Save data
  111.  
  112.     FUNCTION
  113.         This method saves the object's contents to disk.
  114.  
  115.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  116.         superclass, sound.datatype, which writes an IFF 8SVX sample.
  117.  
  118.         If dtw_mode is DTWM_RAW, the object writes a MPEG audio stream to
  119.         the filehandle given.
  120.         (If the class library was compiled with the NO_ENCODER switch
  121.         (not the default), result == 0 and resul2 == ERROR_NOT_IMPLEMENTED
  122.         are returned).
  123.  
  124.     TAGS
  125.         None defined.
  126.  
  127.     RESULT
  128.         Returns 0 for failure (IoErr() returns result2), non-zero
  129.         for success.
  130.  
  131. mpegaudio.datatype/MAIN                               mpegaudio.datatype/MAIN
  132.  
  133.     INTRODUCTION
  134.         Datatypes class for MPEG audio streams.
  135.  
  136.     REQUIREMENTS
  137.         - You need at least Kick/WB 3.0.
  138.  
  139.         - mc68020 (required by the "mpega" decoder).
  140.           This datatype checks the CPU installed and rejects any attempt to
  141.           open it if the CPU is not available.
  142.  
  143.         - "datatypes/sound.datatype", >= V39.
  144.  
  145.     USAGE
  146.         If the datatypes descriptor file was activated, any attempt to load
  147.         a MPEG audio stream using GMultiView, MultiView, AmigaGuide or
  148.         SwitchWindow will load and play the sample.
  149.  
  150.         If you want to save the current sample in mpegaudio.datatype's local
  151.         format, use MultiView's "Project/Save As..." menu (or GMultiView's
  152.         "Project/Save As Raw...").
  153.         (NOT IMPLEMENTED YET)
  154.  
  155.     INSTALLATION
  156.         After unpacking this archive:
  157.         Because this version does not include an Installer script, you have
  158.         to do the installation manually through the shell:
  159.  
  160.           - Unpack this archive and copy the "mpegaudio.datatype" to
  161.             SYS:Classes/DataTypes:
  162.  
  163.      Copy CLONE FROM "mpegaudio.datatype" TO
  164.        "SYS:Classes/DataTypes/mpegaudio.datatype"
  165.  
  166.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  167.             directory.
  168.             If the descriptor already exists, you should not replace it,
  169.             otherwise you may loose "toolnodes" and other settings stored in
  170.             the existing descriptor.
  171.  
  172.      Copy CLONE FROM "MPEG Audio(%|.info)" TO DEVS:Datatypes/
  173.  
  174.     NOTE
  175.         The datatype "hooks" on an external mpeg audio decoder like "mpega".
  176.  
  177.     SOURCE
  178.         Source is fully included here.
  179.  
  180.     AUTHOR
  181.         If you want to blame me, report any bugs, or wants a new version
  182.         send your letter to:
  183.                         Roland Mainz
  184.                         Hohenstaufenstraße 8
  185.                         52388 Nörvenich
  186.                         GERMANY
  187.  
  188.         Phone: (+49)(0)2426/901568
  189.         Fax:   (+49)(0)2426/901569
  190.  
  191.         EMAIL is also available (if you want to send me attachments
  192.         larger than 1MB (up to 5MB, more with my permission):
  193.  
  194.         GISBURN@w-specht.rhein-ruhr.de
  195.  
  196.         Up to August 1998 I'm reachable using this email address, too:
  197.         Reinhold.A.Mainz@KBV.DE
  198.  
  199.         | Please put your name and address in your mails !
  200.         | German mailers should add their phone numbers.
  201.         | See BUGS section above when submitting bug reports.
  202.  
  203.         Sorry, but I can only look once a week for mails.
  204.         If you don't hear something from me within three weeks, please
  205.         send your mail again (but watch about new releases) (problems with
  206.         this email port are caused by reconfigurations, hackers, network
  207.         problems etc.).
  208.  
  209.         The  entire  "mpegaudio.datatype"  package  may  be  noncommercially
  210.         redistributed, provided  that  the package  is always  distributed
  211.         in it's complete  form (including it's documentation). A small
  212.         copy fee  for media costs is okay but any kind of commercial
  213.         distribution is strictly forbidden without my permission !
  214.         Comments and suggestions how to improve this program are
  215.         generally appreciated!
  216.  
  217.         Thanks to David Junod, who wrote the datatypes environment and lots
  218.         of the datatypes example code, Matt Dillon for his DICE, Olaf 
  219.         'Olsen' Barthel for his help, ideas and some text clips from his 
  220.         documentations.
  221.  
  222. mpegaudio.datatype/OM_DISPOSE                   mpegaudio.datatype/OM_DISPOSE
  223.  
  224.     NAME
  225.         OM_DISPOSE -- Delete object
  226.  
  227.     FUNCTION
  228.         Frees the contents of the mpegvideo.datatype instance data
  229.         and passes then the msg to the superclass.
  230.  
  231.     RESULT
  232.         Returns 0 evertimes.
  233.  
  234. mpegaudio.datatype/OM_NEW                           mpegaudio.datatype/OM_NEW
  235.  
  236.     NAME
  237.         OM_NEW -- Create a mpegaudio.datatype object.
  238.  
  239.     FUNCTION
  240.         The OM_NEW method is used to create an instance of the
  241.         mpegaudio.datatype class. This method is passed to the superclass
  242.         first. After this, mpegaudio.datatype loads the sample using
  243.         "mpega.library"'s decoder into memory.
  244.  
  245.     ATTRIBUTES
  246.         The following attributes can be specified at creation time.
  247.  
  248.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  249.             attribute. Only DTST_FILE is supported.
  250.             If any other type was set in a given DTA_SourceType,
  251.             OM_NEW will be rejected.
  252.             Defaults to DTST_FILE.
  253.  
  254.         DTA_Handle -- For DTST_FILE, a BPTR to a lock is expected by
  255.             datatypesclass, which will convert this into a filehandle.
  256.             A DTST_RAM (create empty object) source type requires a NULL
  257.             handle.
  258.  
  259.     NOTE
  260.         If the datatype was compiled with the NO_ENCODER flag set,
  261.         DTA_SourceType == DTST_RAM causes OM_NEW to reject the method.
  262.  
  263.     RESULT
  264.         If the object was created a pointer to the object is returned,
  265.         otherwise NULL is returned.
  266.  
  267.