The Best of Mecomp Multimedia 1

home *** CD-ROM | disk | FTP | other *** search

/ The Best of Mecomp Multimedia 1 / Mecomp-CD.iso / amiga / datatypes / mpvdtc018 / mpegvideo.datatype.doc < prev

Wrap

Text File | 1997-05-27 | 30.4 KB | 724 lines

TABLE OF CONTENTS mpegvideo.datatype/--datasheed-- mpegvideo.datatype/ADTM_LOADFRAME mpegvideo.datatype/DTM_FRAMEBOX mpegvideo.datatype/GM_LAYOUT mpegvideo.datatype/OM_DISPOSE mpegvideo.datatype/OM_NEW mpegvideo.datatype/preferences mpevideo.datatype/DTM_WRITE mpegvideo.datatype/--datasheed-- mpegvideo.datatype/--datasheed-- NAME mpegvideo.datatype -- data type for mpeg video streams SUPERCLASS animation.datatype DESCRIPTION The mpegvideo data type, a sub-class of the animation.datatype, is used to load and play mpeg 1 video streams (Layer I). METHODS OM_NEW -- Create a new animation object from a description file. The source may only be a file. OM_DISPOSE -- Dispose instance and contents (frames, colormaps etc.), then pass msg to superclass OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the method will be executed like OM_SET downstairs. OM_SET -- Pass msg to superclass, and if the mpegvideo.datatype instance is the "top instance", call GM_RENDER if retval from superclass was != 0UL. GM_LAYOUT -- Collect information from superclass, set up struct DTSpecialInfo and send an OM_NOTIFY containing usefull attributes. DTM_FRAMEBOX -- Set up object for a specified environment if FRAMEF_SPECIFY was set in (dtf -> dtf_FrameFlags). ADTM_LOADFRAME -- Fill in struct adtFrame with requested information from internal FrameNode list like bitmap, colormap, samples, etc.. All other methods are passed unchanged to superclass. ATTRIBUTES Following attributes are set by the object and are READ-ONLY for applications: DTA_NominalHoriz -- same as ADTA_Width DTA_NominalVert -- same as ADTA_Height ADTA_Width -- set by video stream ADTA_Height -- set by video stream ADTA_Depth -- set by video stream (or by prefs) ADTA_NumColors -- set by ADTA_Depth ADTA_ColorRegisters -- obj's palette with ADTA_NumColors entries ADTA_CRegs -- obj's palette with ADTA_NumColors entries ADTA_Frames -- total number of frames ADTA_FramesPerSecond -- set by video stream ADTA_ModeID -- calculated by BestModeID or set by prefs ADTA_Remap -- set by prefs file (if the destination screen matches the requirements) ADTA_KeyFrame -- key frame ADTA_Sample -- sample (optional, if a sample is attached) ADTA_SampleLength -- sample length (optional, see ADTA_Sample) ADTA_Period -- sample period (optional, see ADTA_Sample) ADTA_Volume -- sample volume (optional, see ADTA_Sample) ADTA_Cycles -- sample cycle (optional, see ADTA_Sample) BUGS ALPHA preview version !! - If the mpeg video stream is not 100% standart conform, the decoder part of this datatype will CRASH your machine. Innocent memory will be overwritten !! - If you don't have my "paranimdtcpatch" patch running, animation.datatype (animation.datatype 40.7 (28.09.93)) subclasses will suffer under timing problems when two or more animation.datatype objetcs are playing. I've released a matching patch, DON'T blame me for this bug. Any comments for this problem should be related to the "paranimdtcpatch" project. "paranimdtcpatch" is available in the aminet ("util/dtype"). - In large videos, the frames at the end will be played slower than those at the beginning of the file. This is the result of the sequential search internally used (only serious with more than 25000 frames (mc68030/50mhz)). Will be fixed. - The DICECOLOR output is currently __slow__. I'll fix this problem. Another problem is that the colormaps created by DICECOLOR are equal to the global colormap (at colormap's creation time). The suggested behaviour is that each frame has a new colormap (for hi-quality color output). Will be fixed. - vmm.library virtual memory support is ____EXPERIMENTAL____. I cannot say that it's safe because I don't see animation.datatype's source code. But currently, it works __FINE__. (One exception: Enforcer hits may block the system (occured with Apollo 2030 mc68030 board with SCSI and a file as swap area)). If possible, report your working/non-working configuration. - The current releases contain __MUCH__ dead code (25%-30%). This is caused by syntax checking etc. functions, the 24 bit dithering functions etc. which are not visible/usable in the public versions. TODO - better error handling (and error messages) - code cleanup - bug fixing - Writing an amigaguide document - HAM/EHB output HISTORY V1.1 First (official) public release. V1.2 Major code cleanup. I decided to rebuild the whole project from scratch instead of releasing my internal V1.8. The reason is that many things coded in it wasn't done with the required care. Now I try to fix this. - Sorry, but in the V1.1 release, I've forgotten the COPYRIGHT notice. Because I don't have the original ones (my code was a mergin of mpeg_play 1.X, 2.0, I've taken them from the mpeg_play 2.0 distribution). - Implemented the NOPFRAMES and NOBFRAMES switch (for those people who like it). - The loader now returns usefull return codes instead of failing silently. - Decrased the default depth from 7 to 5 planes. This is a more reliable default value for grayscale mpeg videos (screen or window). - Implemented "DICECOLOR" and "ORDERED" dithering. The options COLORERROR and DICESKIP are for fine-tuning speed <--> color output. - Introduced MAXFRAME (maximum number of frame to load) and SKIPFRAMES to allow loading of large videos. - MODEID option added (for those which don't like the default settings). - The datatypes descriptor file was WRONG. Now it should be correct. If not, send me a mail (and if possible, the sample file which won't work (packed with LhA for compression and CHECKSUMMING). (Later versions of the descriptor should use additional code to check the data). V1.3 - COLOR output implemented. - DICECOLOR: Found a bug (?? very strange one ??) in my code which avoids the usage of a frame palette. DICECOLOR was intended to produce high-quality per frame color remapping instead using a global anim palette. Broken (e.g. working, but after a frame is finished, the color table isn't cleared for now...). - I found out that the most time is consumed by the WritePixelArray and copy functions. Later versions should contain a custom WritePixelArray replacement which should be able to write directly into FAST-RAM instead of writing into CHIP-RAM and them do a copy into FAST-RAM. This would save __MUCH__ time. - Silly mistake: A SetIoErr( 0L ); len = FRead( ..., requested ); sequence returns under various fs IoErr() == (-1L) or something else. The loader then aborts with this error code. (The code worked with RAM: disk, my VideoCD-fs ("white book" mode)) and AMICDROM, but wasn't tested with FFS or something else). The code now uses Read instead of FRead, checks for (len != requested), and only if TRUE IoErr() will be checked for any error. - Introduced BUFFER preferences option. - A CTRL-D signal send to the loading process now stops the load. This feature was implemented in V1.2, but I forgot to write it down here. - The autodoc now has a TOC (table of contents). - Support for Martin Apel's VMM (Virtual Memory Manager). (USEVMM switch in prefs file). The bitmaps can now be in virtual memory (the colormaps are traditional allocated by GetColorMap and cannot be in virtual memory (not yet nor in the future !)). The mpegvideo.datatype uses the vmm.library, this allows virtual memory usage even if the vmm.prefs disables virtual memory for all other tasks. NOTE: VMM is Shareware !! V1.4 - vmm.library is now opened on demand (e.g. the USEVMM switch was set in the prefs file) inside the OM_NEW method. This fixes two problems: First: vmm.library was opened even it wasn't used. Second: OpenLibrary( "vmm.library", ... ) inside the LibInit function caused various problems. vmm.library will be closed by LibExpuge function. - Removed serial verbose output. Now, if the VERBOSE switch was set in the prefs file, all verbose output will be printed to "CON://///auto/wait/close/inactive". - Set the SC NOOPTIMIZERPEEPHOLE switch for mc68060 support: phase5 said that SAS/C 6.56 has a small bug in the peephole optimizer which may cause trouble with mc68060. The peephole optimizer will be turned on again if I know more details (and a workaround). - The product of LUM_RANGE * CR_RANGE * CB_RANGE was limited to a maximum of 512. LUM_RANGE, CR_RANGE, CB_RANGE can now have any positive value up to 255. A value of 0 is treated as 1, fixing the problem of a possible division by zero. - Found a bug in COLOR dithering, which causes quality loss and color disorientation. Fixing this bug will take MUCH time. Not fixed yet. - To match the "DataTypes proposal", changes have been made: 1. The location of the prefs file is now ENV:Classes/DataTypes/ mpegvideo.prefs instead of ENV:DataTypes/mpegvideo.prefs 2. Subclasses of mpegvideo.datatype are not supported. Any attempt to create a subclass object of mpegvideo.datatype will be rejected by mpegvideo.datatype. - Partial code cleanup. I've implemented partial support for output depths up to 16 bits. Currently, I'm limited to a maximum depth of 8 bitplanes (e.g. 256 colors) for two reasons: First, the system WritePixelArray8 function handles only byte width pen indexes, second, animation.datatype handles only a bitmaps up to 8 planes. Future releases of animation.datatype may handle deeper bitplanes. (Custom players like my DBufDTAnim which are using their own display code are able to display deeper bitmaps yet.) - Found out a little problem: When using VMM (swap file) with Enforcer, enforcer hits may block your system (occured on a A2000 Apollo 2030 mc68030 board). Who knows an answer for this problem ? V1.5 Minor changes to support special compiled versions for 68020+, fpu etc. - Implemented the IGNOREERRORS switch, which attempts to ignore any error during loading. - Removed some dead code. V1.6 The datatypes supports now scaling and sound. Sound was implemented for two reasons: 1. For those streams which are distributed with a matching sound file. 2. I'm reworking mpegsystem.datatype (which can play system streams, e.g. video with interleaved audio). The goal is to implement mpegsystem.datatype as a subclass of mpegvideo.datatype. The audio stream will be parsed using mpegaudio.datatype. Note that mpegvideo.datatype is still a GID_ANIMATION type datatype. The GID_#? idetifiers belongs to the source data, not the modifications done by a datatype code (a mpeg 1 video stream does not contain any audio information, the sound is attached later). - Implemented the WIDTH and HEIGHT options in the prefs file to support scaling. - Implemented SAMPLE and VOLUME options to support sound. - Now uses BestModeID for selecting the screen mode of the animation. The MODEID preference option overides this. The old behavior was to set the ADTA_ModeID attribute only if the MODEID prefs option was set, otherwise the default from animation.datatype was taken (which was everytimes 0). - Fixed the FPS preference option. If it was set, the value was got from the depth option instead using the given value. - Implemented a processing gauge as requested by Allan Odgaard (Duff@DK-Online.DK) and many other people. The matching NOPROGRESSGAUGE switch disables it. If the input filehandle is a pipe, the gauge may not work properly. - Implemented a lowermem limit (MINTOTALMEM option) for those people who wants to see at least the beginning of a big anim (idea by Allan Odgaard (Duff@DK-Online.DK)). - Implemented multi-line preferences, supports comments and per-project settings (MATCHPROJECT option). The old preference files/vars are compatible. - The stack size for the OM_NEW method is now checked. If the required size (curretly 12kb) isn't available, a requester will notify the user and the method returns an error. V1.7 - Recompiled with SAS/C 6.57. Switched the peephole optimizer on (see V1.4 bugs). - Rewrote the DICECOLOR dithering/remapping code. The DICECOLOR color mode now creates a colormap per frame (animation.datatype 40.7 does not support these colormap changes per frame (it's output looks like a color trash). Custom animation players which uses animation.datatype subclasses for loading (like my DBufDTAnim) don't have this problem. animation.datatype V41 will support these colormaps-per-frame. I changed the algorithm from a single-pass into a multi-pass operation, which allows the code to run on other output modes like ORDERED or FS (Floyd-Steinberg). A side-effect of this change is that options like COLORERROR and DICESKIP are selected automatically, which is more user-friendly. If you want to get the old DICECOLOR output, use DITHER=COLOR PALETTEPERFRAME options. - The mpegvideo.datatype uses 24 bit-colors internally and writes 32 bits per (r,b,g) gun. Now the high order bits of each color gun are replicated through the whole INT32. - Fixed a bug in the SAMPLE option, which caused possible crashes. - Fixed a bug in LibExpunge (didn't check lib_OpenCnt), which is also present in all my other external BOOSI classes (and datatypes). Thanks to Guenter Niki (gniki@informatik.uni-rostok.de) for reporting this bug. - Implemented the mpeg saveing code (mpeg encoder). Currently, only mpeg-1 streams are written out. (Will be enabled in the public versions ONLY upon request; code is currently under construction). - Increased the stack requirements from 12kb up to 16kb, mainly to allow more recursive operations. - Implemented random access to frames (e.g you need not to load the whole animation, decodung is done on the fly). (Will be enabled in the public versions ONLY upon request; code is currently under construction, the matching LOADALL switch it set everytimes). V1.8 - Added partial support for mpeg-2 (MPEG-2 does NOT work yet !), both encoder+decoder. - Added my own WritePixelArray8 replacement, which operates directly on the fast-mem bitmaps. This saves some internal copies, chipmem buffer for WPA8 etc. - Added my own scaling routine, replacing graphics.library/BitMapScale (which needs chipmem as temp. buffer). Does not work properly yet. - Fixed the gauge, which didn't work correctly with large streams (>= 8MB). Fixed. - The gauge ha now a text info, which shows the remaining time to decode. - Added experimental stack swapping code. The "Need more stack"- requester has been removed for this reason. This also fixes a possible deadlock of "input.device" because the GM_LAYOUT method was running with low stack. Fixed. - Color table setup now retries color table build with an increased COLORERROR if table (set by LUM_RANGE * CR_RANGE * CB_RANGE) does not fit. This allows any #?_RANGE value. - Fixed different problems within color setup. Now this should work with a higher quality, and a little bit faster. - Fixed the descriptor, which din't match all mpeg video streams. Fixed. - DTM_WRITE should return ERROR_NOT_IMPLEMENTED if DTWM_RAW mode is requested (becuase the encoder has been disabled, e.g. commented out). Now this is correctly done. Fixed. - The 06060-Version now checks for the AFF_68060 (1L<<7) execbase fl ag instead using the AFF_68040. Fixed. - Added QUALITY prefs option and matching float-dct code. NOTES SEE ALSO animation.datatype, mpegsystem.datatype, mpegvideo.datatype picmovie.datatype, directory.datatype, markabletextdtclass, paranimdtcpatch mpegvideo.datatype/ADTM_LOADFRAME mpegvideo.datatype/ADTM_LOADFRAME NAME ADTM_LOADFRAME -- Load frame FUNCTION The ADTM_LOADFRAME method is used to obtain the bitmap and timing data of the animation. The given timestamp will be used to find the closest timestamp in the internal FrameNode list. If it was found, the corresponding timing, bitmap, colormap and sound data are stored into the struct adtFrame, RESULT Returns always non-zero. mpegvideo.datatype/DTM_FRAMEBOX mpegvideo.datatype/DTM_FRAMEBOX NAME DTM_FRAMEBOX -- Set up object for a specified environment FUNCTION The DTM_FRAMEBOX method is used to set up for a specified environment. This method is passed to the superclass after mpegvideo.datatype instance finished it's work. Only if FRAMEF_SPECIFY is set in (dtf -> dtf_FrameFlags), the mpegvideo.datatype instance will modify the ADTA_Remap to FALSE if the NOREMAP switch in the prefs file was set and the animation depth matches the given (frameinfo -> fri_Dimensions . Depth) depth. RESULT The value from the superclass is returned. SEE ALSO 3.1_Examples2:DataTypes/Src/ClipView/clipview.c mpegvideo.datatype/GM_LAYOUT mpegvideo.datatype/GM_LAYOUT NAME GM_LAYOUT -- Layout animation object FUNCTION This method is passed to the superclass first. Then it collects information from superclass, set up struct DTSpecialInfo and send an OM_NOTIFY containing the following attributes: DTA_VisibleVert, (DTA_Domain -> Height) DTA_TotalVert, (same as ADTA_Height) DTA_NominalVert, (same as ADTA_Height) DTA_VertUnit, 1UL, DTA_VisibleHoriz, (DTA_Domain -> Width), DTA_TotalHoriz, (same as ADTA_Width), DTA_NominalHoriz, (same as ADTA_Width), DTA_HorizUnit, 1UL, GA_ID, (GadgetID), DTA_Title, (same as DTA_Name), DTA_Busy, FALSE, DTA_Sync, TRUE RESULT The value from the superclass is returned. mpegvideo.datatype/OM_DISPOSE mpegvideo.datatype/OM_DISPOSE NAME OM_DISPOSE -- Delete a mpegvideo.datatype object. FUNCTION The OM_DISPOSE method is used to delete an instance of the mpegvideo.datatype class. This method is passed to the superclass when it has completed. This method frees all frame nodes and their contents (pictures, their colormaps, sounds etc.). RESULT The object is deleted. 0UL is returned. mpegvideo.datatype/OM_NEW mpegvideo.datatype/OM_NEW NAME OM_NEW -- Create a mpegvideo.datatype object. FUNCTION The OM_NEW method is used to create an instance of the mpegvideo.datatype class. This method is passed to the superclass first. After this, mpegvideo.datatype loads it's preference file (and the sound file, if one was specified), parses the whole video stream, putting pictures into memory. Any fatal error aborts the load, non-serious errors are reported. Subclasses of mpegvideo.datatype are not supported. Any attempt to create a subclass object of mpegvideo.datatype will be rejected by this method. ATTRIBUTES The following attributes can be specified at creation time. DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle attribute. Currently, only a source type of DTST_FILE is supported. If any other type was set in a given DTA_SourceType, OM_NEW will be rejected with result2 == ERROR_OBJECT_WRONG_TYPE. Defaults to DTST_FILE. DTA_Handle (BPTR) -- If DTA_SourceType is DTST_FILE, the given file will be used as an mpeg video stream to read in. RESULT If the object was created a pointer to the object is returned, otherwise NULL is returned. mpegvideo.datatype/preferences mpegvideo.datatype/preferences NAME preferences DESCRIPTION The "ENV:Classes/DataTypes/mpegvideo.prefs" file contains global settings for the datatype. The preferences file is an ASCII file containing one line where the preferences can be set. It can be superset by a local variable with the same name. Each line can contain settings, special settings for some projects can be set using the MATCHPROJECT option. Lines beginning with a '#' or ';' chars are treated as comments. Lines are limitted to 256 chars. TEMPLATE MATCHPROJECT/K,MODEID/K/N,WIDTH/K/N,HEIGHT/K/N,DEPTH/K/N,DITHER/K, LUM_RANGE/K/N,CR_RANGE/K/N,CB_RANGE/K/N,COLORERROR/K/N, PALETTEPERFRAME/S,NOREMAP/S,MAXFRAME/K/N,SKIPFRAMES/K/N,FPS/K/N, NOPFRAMES/S,NOBFRAMES/S,SAMPLE/K,VOLUME/K/N,BUFFER/K/N,LOADALL/S, USEVMM/S,MINTOTALMEM/K/N,IGNOREERRORS/S,VERBOSE/S,NOPROGRESSGAUGE/S, QUALITY/S MATCHPROJECT -- The settings in this line belongs only to this project(s), e.g. if the case-insensitive pattern does not match, this line is ignored. The maximum length of the pattern is 128 chars. Defaults to #?, which matches any project. MODEID -- Select screen mode id of datatype (will be stored in ADTA_ModeID). Note that the DOS ReadArgs function used for parsing fetches a SIGNED long. The bit 31 will be represented by minus '-'. (example: "MODEID=266240" sets the mode to the A2024 screen mode id) Defaults to 0, which means: Use the best screenmode available for the given width, height and depth. WIDTH -- Set the animation's width. The video will be scaled to this width. Defaults to 0, which means: Use video's width. HEIGHT -- Set the animation's height. The video will be scaled to this height. Defaults to 0, which means: Use video's height. DEPTH -- depth for the selected scaling mode A value describing the "depth" of the animation. 1 upto 8 are valid, under- or overflows will be truncated to the maximum supported. The default depth will be selected by the DITHER mode. DITHER -- dither type, one of GRAY -- grayscale output (default) HAM -- ham (ham4/ham6/ham8 etc.) (n/a) EHB -- extra halfbright (n/a) COLOR -- color output HYBRID -- hybrid dither (n/a) FS2 -- floyd-steinberg dithering (n/a) FS4 -- dito. (n/a) ORDERED -- ordered dither GRAY is the grayscale mode. HAM (hold-and-modify) mode: not implemented yet EHB (extra halfbright mode): not implemented yet COLOR remaps the frames into a fixed color space. Defaults to GRAY. LUM_RANGE -- sets the number of colors assigned to the luminance component when dithering the image. The product of LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of colors selected by the DEPTH option. This will only affect ORDERED and COLOR dithering and the base palette of the DICECOLOR remapping. Any value between 1 upto 255 is allowed, 0 is treated as 1. Defaults to 8. CR_RANGE -- sets the number of colors assigned to the red component of the chrominace range when dithering the image. The product of LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of colors selected by the DEPTH option. This will only affect ORDERED and COLOR dithering and the base palette of the DICECOLOR remapping. Any value between 1 upto 255 is allowed, 0 is treated as 1. Defaults to 4. CB_RANGE -- sets the number of colors assigned to the blue component of the chrominace range when dithering the image. The product of LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of colors selected by the DEPTH option. This will only affect ORDERED and COLOR dithering and the base palette of the DICECOLOR remapping. Any value between 1 upto 255 is allowed, 0 is treated as 1. Defaults to 4. COLORERROR -- Set the error range when allocating colors. The error range is used for color matching (like this: if( ABS( (pixel . red) - (colormap . red) ) + ABS( <dito. green> ) + ABS( <dito. blue> ) < colorerror ) then use this color index). A low value (0) means high quality remapping and slow remapping, high values (50) means low quality (using less color indexes). The value set here will also affect DICECOLOR remapping, because the search algorithm is the same. Defaults to 0. PALETTEPERFRAME -- Create a own palette for each frame. MAXFRAME -- Maximum number of frames to load. Defaults to 0, which means: Load all frames. SKIPFRAMES -- Load only the n-th frame of an animation. The internal timing (e.g. time code) is not affected, so the FPS value will be correct. Defaults to 0 which means: Skip no frame. FPS -- frames per second Defaults to 0, which means: overtake fps rate from video stream. Setting the FPS value also affects an attched sound. The period of the sample (e.g. the playback speed) will everytimes as long as the frame is displayed. NOPFRAMES -- ignore any type P frames (predicted frames) when loading. NOBFRAMES -- ignore any type B frames (bidirectional frames) when loading. SAMPLE -- Attach the given sample to the animation. The sample will be loaded using datatypes (GID_SOUND). Only one sample can be attached to one video stream, any following attempt to attach the sample will be ignored. VOLUME -- Volume of the sound when playing. Defaults to 64, which is the maximum. A value greater than 64 will be set to 64. BUFFER -- read buffers size. Minimum is 2048, lower values are set to 2048. Defaults to 2048. LOADALL -- load all frames before displaying it. Currently everytimes set. USEVMM -- Use Martin Apel's vmm.library for bitmaps (experimental, but works __fine__). MINTOTALMEM -- Minimum total memory available. If less memory available, abort loading. Defaults to 0, which means: Don't use this option. IGNOREERRORS -- Ignore errors while parsing/decoding etc. VERBOSE -- Verbose output. Prints out current frame etc., some statistical information and maybe, debugging infos. Verbose output will be printed in a console window ("CON://///auto/wait/close/inactive/MPEG Video DataType"). NOPROGRESSGAUGE -- Disables the progress gauge which is displayed during loading of the mpeg stream. QUALITY -- If set, mpegvideo.datatype uses floating-point dct decoding, which results in a better output quality. NOTE An invalid prefs file line will force the default settings for this line and the VERBOSE option. BUGS - Low memory may cause that the prefs file won't be parsed. - Lines are limitted to 256 chars mpevideo.datatype/DTM_WRITE mpevideo.datatype/DTM_WRITE NAME DTM_WRITE -- Save data FUNCTION This method saves the object's contents to disk. If dtw_Mode is DTWM_IFF, the method is passed unchanged to the superclass, animation.datatype, which writes a single IFF ILBM picture. The local data format (e.g. dtw_Mode == DTWM_RAW) is currently not supported, this method returns 0UL (and result2 == ERROR_NOT_IMPLEMENTED) in that case. RESULT Returns 0 for failure (IoErr() returns result2), non-zero for success.