home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Multimed / Multimed.zip / divempeg.zip / README.TXT < prev   
Text File  |  1995-07-10  |  18KB  |  443 lines
  1. This is the README FILE of DIMP version 0.9: a multithreaded MPEG player for 
  2. OS/2 Warp 3.0 using DIVE (Direct Interface to Video Extensions) written by:
  3.  
  4.   Peter Van Geit
  5.   Student at the University of Ghent, Belgium (the small country between France & 
  6.                                                   Germany)
  7.   vg@iris.elis.rug.ac.be
  8.  
  9. Please send your comments/suggestions/questions to the above adress.
  10.  
  11. 0] CONTENTS
  12.  
  13.   1] Product description
  14.   2] Copyright notice
  15.   3] Contents
  16.     3.1] Executables
  17.     3.2] Source code
  18.   4] Writing your own MPEG player
  19.   5] How the player works
  20.   6] VIDEO.DLL description
  21.   7] DITHER.DLL description
  22.   8] DIVE.DLL description
  23.   9] Player performance
  24.  
  25. 1] PRODUCT DESCRIPTION
  26.   
  27.   This player is a port of the Berkeley Plateau Research Group MPEG-1
  28.   player version 2.0. It implements the standard described in the
  29.   Committee Draft ISO/IEC CD 11172. This UNIX-player uses X-Windows to 
  30.   display the video sequence. The player doesn't implement real-time 
  31.   synchronisation nor does it supports audio streams. It is shipped with 
  32.   various dithering algorythms. Until now the player has been ported to
  33.   several platforms including DOS and Windows. The source can be freely
  34.   obtained via anonymous ftp from "toe.cs.berkeley.edu" in 
  35.   "/pub/multimedia/mpeg/mpeg-2.0.tar.Z"
  36.  
  37.   Below I include the copyright notice of the original player:
  38.  
  39. /*
  40.  * Copyright (c) 1992 The Regents of the University of California.
  41.  * All rights reserved.
  42.  * 
  43.  * Permission to use, copy, modify, and distribute this software and its
  44.  * documentation for any purpose, without fee, and without written agreement is
  45.  * hereby granted, provided that the above copyright notice and the following
  46.  * two paragraphs appear in all copies of this software.
  47.  * 
  48.  * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
  49.  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
  50.  * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  51.  * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  52.  * 
  53.  * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  54.  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  55.  * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  56.  * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  57.  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  58.  */
  59.  
  60.   I ported the player to IBM OS/2 Warp 3.0 and named it DIVE (DIve MPeg). It
  61.   consists of three parts:
  62.  
  63.     video.dll : a dynamic link library which contains the MPEG decoding routines
  64.     dither.dll: a dynamic link library which includes many dithering algorythms
  65.     dimp.exe  : the player. It implements the interface and manages the above dll's
  66.  
  67.   The two above dll's are completely independent and REUSABLE (definition files &
  68.   headers needed to use them are included) in other applications, the player 
  69.   dimp.exe is nothing more than a demonstration of how to use these libraries. 
  70.   Furthermore I think this player is a very good example showing you how to use 
  71.   DIVE. The player runs under Presentation Manager and has a very functional 
  72.   interface. It uses two threads: one to respond to user actions and one thread that 
  73.   handles the decoding. The player uses the dive.dll dynamic link library for fast 
  74.   screen access. DIVE functionality includes:  
  75.  
  76.     Direct video frame buffer access
  77.     Video hardware interrogation
  78.     Color space conversion (=dithering)
  79.     Palette conversion
  80.     Auto-resizing
  81.  
  82.   The player comes in two versions:
  83.  
  84.     dimp.exe  : optimize for speed
  85.     dimp2.exe : generates extensive statistical information
  86.  
  87.   You can start the players at the command line or use drape-and-drop
  88.  
  89. 2] COPYRIGHT NOTICE
  90.  
  91.   The changes I made to the original source (which is freely distributable) as 
  92.   well as the new source files I wrote are FREELY distributable/modifiable/
  93.   usable, EXCEPT for commercial goals. Also the dynamic link libraries 
  94.   "video.dll","video2.dll" and "dither.dll" may be used FREELY, EXCEPT for 
  95.   commercial goals. The author of this player shall not be held responsible in 
  96.   any way for any damage caused by this player.
  97.  
  98. 3] CONTENTS
  99.  
  100.   3.1] PLAYER EXECUTABLES: (dimpexe.zip)
  101.  
  102.     dimp.exe  : needs dither.dll and video.dll
  103.                 (This one is optimized for speed)
  104.  
  105.     dimp2.exe : needs dither.dll and video2.dll 
  106.                 (This one generates extensive statistical output)
  107.  
  108.   3.1] PLAYER SOURCE FILES: (dimpsrc.zip)
  109.     
  110.     dimp.h    : player header
  111.     dimp.c    : player main file
  112.     dimp.def  : player definition file
  113.     dimp.rc   : player resource file
  114.     
  115.     *.ico     : various icons used by the player
  116.     *.dlg     : various dialogs used by the player
  117.  
  118.     dither.dll: dynamic link library containing dithering routines
  119.                 (included in dimpexe.zip)
  120.     dither.def: corresponding definition file (used to produce the import
  121.                 library which is linked with the player)
  122.     pvgdith.h : corresponding header file containing the declarations of the
  123.                 functions implemented in dither.dll used by the player
  124.                 (this file must be #included by the player)
  125.  
  126.     video.dll : dynamic link library containg MPEG decoding routines
  127.                 (included in dimpexe.zip)
  128.     video2.dll: idem but this one generates statistical info
  129.                 (included in dimpexe.zip)
  130.     video.def : corresponding definition file (used to produce the import
  131.                 library which is linked with the player)
  132.     video2.def: idem but for video2.dll
  133.     pvgvideo.h: corresponding header file containing the declarations of the
  134.                 functions implemented in video(2).dll used by the player
  135.                 (this file must be #included by the player)
  136.  
  137.     dimp.mak  : player make file 
  138.  
  139.   3.3] Tools used
  140.  
  141.   I wrote this player under IBM OS/2 Warp 3.0 with the IBM C/Set++ 2.1 compiler
  142.   (latest CSD's) and the IBM Warp 3.0 Toolkit. Therefore if you use the same
  143.   configuration everything should compile without problems.
  144.  
  145.   You can generate an executable running "makeall.cmd" after customizing the
  146.   makefile "dimp.mak"
  147.                                                           
  148. 4] WRITING YOUR OWN MPEG PLAYER
  149.  
  150.   You can write your own MPEG player in just a few hours by using the 
  151.   routines provided in the dither.dll and video(2).dll dynamic link 
  152.   libraries (see below for a description of the routines). All you need 
  153.   to do is to:
  154.   
  155.     1) include "pvgdith.h" and "pvgvideo.h" in your player source file
  156.     
  157.     2) generate the import libraries "dither.lib" and "video.lib" via:
  158.       
  159.       implib dither.lib dither.def
  160.       implib video.lib video.def (use video2.def to generate stat. info)
  161.  
  162.     3) link the import libraries with the object code of your own player
  163.  
  164.   See "dimp.c" and "dimp.mak" for more information on the usage
  165.  
  166.   You don't need it for the usage of the libraries but if you would be 
  167.   interested in the source code of the video(2) and dither dynamic link 
  168.   libraries, send me a mail at my adress mentionned above.
  169.  
  170. 5] HOW THE PLAYER WORKS
  171.   
  172.    EXECUTABLE          ACTIONS       DYN. LNK. LIBRARIES
  173.  
  174.   +----------+        initialize        +------------+
  175.   | DIMP.EXE |      ---------------->   | VIDEO.DLL  |
  176.   | ( MPEG   |      decode next frame   | ( MPEG     |
  177.   | player)  |      ---------------->   |  decoding) |
  178.   |          |    24-bit decoded frame  |            |
  179.   |          |      <----------------   +------------+
  180.   |          |
  181.   |          |         initialize       +------------+
  182.   |          |      ---------------->   | DITHER.DLL |
  183.   |          |    24-bit decoded frame  | ( 8-bit    |
  184.   |          |      ---------------->   | dithering) |
  185.   |          |    8-bit dithered frame  |            |
  186.   |          |      <----------------   +------------+
  187.   |          |
  188.   |          |         initialize       +------------+
  189.   |          |      ---------------->   |  DIVE.DLL  |           DISPLAY
  190.   |          |    8-bit dithered frame  |            |  -------> HARDWARE
  191.   +----------+      ---------------->   +------------+
  192.   
  193. 6] VIDEO.DLL DESCRIPTION
  194.  
  195.   The video.dll (video2.dll for the statistical version) dynamic link library
  196.   implements the folowing datatypes and functions which are declared in 
  197.   "pvgvideo.h". See "dimp.c" to know in which order the routines functions
  198.   should be called.
  199.  
  200.   void init_tables();
  201.  
  202.     Function called first to initialize the Huffman tables used for decoding
  203.   
  204.   VidStream 
  205.     
  206.     Datatype that represents a MPEG-video sequence
  207.   
  208.   VidStream * NewVidStream (char * fname, int bufLength, int loop, int quiet,
  209.                             
  210.                             int noDisplay, int ditherType);
  211.  
  212.     Function called at the beginning to create a new video sequence structure
  213.     which contains info/datastructures needed during decoding:
  214.  
  215.     fname       : the filename of the MPG-file
  216.     bufLength   : 80000 should do fine
  217.     loop        : 0 : stop at the end of the video sequence
  218.                   1 : restart from the beginning at the end of the sequence
  219.     noDisplay   : ignore this parameter
  220.     ditherType  : the dithering method used (MPEG-decoding needs to know this)
  221.                   see 7] for a description of possible values for this parameter
  222.     return value: pointer to the video sequence structure. This pointer should
  223.                   be passed to the function below after decoding is done:
  224.  
  225.   void DestroyVidStream (VidStream *astream );   
  226.  
  227.     Destroys the allocated datastructures needed during decoding
  228.  
  229.   typedef int TimeStamp;
  230.  
  231.     Datatype used for generating timing info
  232.   
  233.   int mpegVidRsrc (TimeStamp time_stamp , VidStream *vid_stream, char **
  234.                   pditherFlags);
  235.  
  236.     Decodes the next (whichever comes first):
  237.       
  238.       MPEG slice 
  239.       MPEG frame
  240.       MB_QUANTUM macro-blocks (declared in pvgvideo.h)
  241.   
  242.     time_stamp  : always 0 should do fine
  243.     vid_stream  : the pointer returned by NewVidStream
  244.     pditherFlags: will be initialized with the correct values. This parameter
  245.                   should afterwards be passed through DoDitherImage (see below)
  246.                   You only need to declare it.
  247.     return value:
  248.  
  249.     (1) When mpegVidRsrc is called the FIRST time:
  250.  
  251.     MPEG_INFO 
  252.       mpeg stream was valid + info about mpeg-video is available 
  253.       (cfr. dimp.c where you can find the info)
  254.     MPEG_INVALID 
  255.       mpeg stream was not valid
  256.     MPEG_NULL 2
  257.       NewVidStream was NOT called first
  258.  
  259.     (2) When mpegVidRsrc is called after the first time: 
  260.  
  261.     MPEG_MB_QUANTUM
  262.       MB_QUANTUM of macroblocks decoded 
  263.     MPEG_SLICE
  264.       a slice was decoded 
  265.     MPEG_FRAME_SKIP
  266.       a frame encountered that was labeled as to be skipped 
  267.     MPEG_FRAME_NODISP 
  268.       a frame decoded that must not be displayed yet 
  269.     MPEG_FRAME_DISP 
  270.       a frame decoded that must be displayed 
  271.     MPEG_ERROR 
  272.       an error was encountered, but processing can continue 
  273.     MPEG_DONE_DISP
  274.       end of mpeg-video encountered, display last frame
  275.     MPEG_DONE_NODISP 
  276.       end of mpeg-video encountered, no frame left to display 
  277.  
  278.   void ResetVidStream(void);
  279.     
  280.     Called after decoding the last frame when looping
  281.  
  282.   void VidStreamFlags(int type, int loop, int noDisplay);
  283.  
  284.     Called whenever the method of dithering is changed
  285.     type      : the new dithering method to be used (see below for possible 
  286.                 values)
  287.     loop      : ignore this one
  288.     noDisplay : ignore this one
  289.  
  290.   void TogglePFlag(void);
  291.  
  292.     Toggles decoding of P-frames on/off. Initially it will be on.
  293.   
  294.   void ToggleBFlag(void);
  295.  
  296.     Toggles decoding of B-frames on/off. Initially it will be on.
  297.     With these two functions you can accelerate the video sequence by decoding:
  298.     
  299.       I/P/B frames (all frames)                            -> normal decoding
  300.       I/P frames only (call ToggleBFlag())                 -> faster decoding
  301.       I frames only (call TogglePFlag() and ToggleBFlag()) -> fastest decoding
  302.   
  303.     PS: P-frames are needed to decode B-frames correctly 
  304.  
  305.   typedef void FNSTAT();
  306.  
  307.     Used in the statistical version of the player (which generates extensive
  308.     stat. info about the MPEG video stream currently being decoded)
  309.  
  310.   typedef FNSTAT * PFNSTAT;
  311.  
  312.     Pointer to the previous function type
  313.  
  314.   void PassStats(int showEachFlg, PFNSTAT ShowOneStat, PFNSTAT ShowAllStats);
  315.  
  316.     Used to pass the functions:
  317.       
  318.       *ShowOneStat  : will be called by decode2.dll when stat. information is
  319.                      available about the current frame
  320.       *ShowAllStats : will be called by decode2.dll when stat. information is
  321.                      available about the current video sequence
  322.       showEachFlag : 1 : *ShowOneStat is called after decoding each frame
  323.                      0 : ShowOneStat is never called
  324.   Statval;
  325.  
  326.     Structure used to pass statistical info (see pvgvideo.h for details)
  327.  
  328.   void GetStats(Statval ** stat);
  329.  
  330.     Call this function to get statistical info about the current frame/whole
  331.     sequence after it is ready (when ShoneOne(All)Stat(s) is called)
  332.  
  333. 7] DITHER.DLL DESCRIPTION
  334.  
  335.   The dither.dll dynamic link library implements functions/data types 
  336.   declared in "pvgdith.h". Look at "dimp.c" to know in which order you should
  337.   call these functions:
  338.  
  339.   void InitDither(int type, int lum_range, int cr_range, int cb_range, PBYTE
  340.                   * pPalette, PBYTE *pPal2);
  341.  
  342.     Initializes the necessary data structures needed during dithering
  343.     type   : the used dither method. Here follows a list of possible dither types:
  344.       
  345.       (1)  8-bit color dithering methods
  346.       HYBRID_DITHER 
  347.       HYBRID2_DITHER
  348.       FS4_DITHER
  349.       FS2_DITHER
  350.       FS2FAST_DITHER 
  351.       ORDERED_DITHER 
  352.       ORDERED2_DITHER 
  353.       MBORDERED_DITHER 
  354.       Twox2_DITHER
  355.       
  356.       (2) 7-bit gray dithering 
  357.       GRAY_DITHER 
  358.  
  359.       (3) Full color dithering
  360.       FULL_COLOR_DITHER 
  361.  
  362.       (4) No dithering is performed
  363.       NO_DITHER 
  364.       
  365.       (5) Black/White dithering
  366.       MONO_DITHER 
  367.       MONO_THRESHOLD 
  368.  
  369.     lum_range : 8 will do fine
  370.     cr_range  : 4 will do fine
  371.     cb_range  : 4 will do fine
  372.     pPalette  : OS/2 256 color palette (256 4-byte entries, first three bytes
  373.                 correspond with the R,G and B values.
  374.     pPal2     : exact copy of the previous parameter
  375.  
  376.     void TerminateDither (PBYTE pPalette, PBYTE pPal2);
  377.  
  378.       Must be called at the end to free all allocated resources used during
  379.       dithering
  380.  
  381.     void DoDitherImage(unsigned char *l, unsigned char *Cr, unsigned char *Cb,
  382.     unsigned char *disp, int w, int h, char * f);
  383.  
  384.       Dithers a 24-bit image (2x2 color subsampled) using the current dithering
  385.       method
  386.  
  387.       l     : pointer to the luminance pane (use "current->luminance" field
  388.               of your VidStream structure)
  389.       Cr    : pointer to the Cr color pane (use "current->Cr" field of your 
  390.               VidStream structure)
  391.       Cb    : pointer to the Cb color pane (use "current->Cb" field of your 
  392.               VidStream structure)
  393.       disp  : pointer to the buffer where the image should be dithered to
  394.       w     : width of the image in pixels (use "mb_width" field of your
  395.               VidStream structure multiplied by 16)
  396.       h     : height of the image in pixels (use "mb_height" field of your
  397.               VidStream structure multiplied by 16)
  398.       f     : dither-flags returned by mpegVidRsrc (use the ditherFlag parameter
  399.               returned by mpegVidRsrc)
  400.  
  401. 8] DIVE.DLL DESCRIPTION                                
  402.  
  403.   Information about the routines of this dynamic link library can be found
  404.   in the documentation provided with the IBM Warp 3.0 Toolkit. For info
  405.   on using the routines cfr. "dimp.c".
  406.  
  407. 9] PLAYER PERFORMANCE
  408.  
  409.   I tested the player with many MPEG sequences. Most of them, except for a few,
  410.   seemed to work well. Via EXTRA (Execution Trace Analyzer, included in the
  411.   Warp Toolkit) I was able to determine the percentage processor usage (PPU) of 
  412.   the three components of the player: (25sec video, dither method = 
  413.   ORDERED_DITHER)
  414.  
  415.   mpg-file ->  bobo    mjackson whacking iicm     waterski son
  416.  
  417.   dimp.exe     11      13       12       10       13       12
  418.   video.dll    68      64       66       68       64       62
  419.   dither.dll   20      23       22       22       23       25
  420.  
  421.   It seams that the PPU is relatively constant for different MPEG sequences.
  422.   The decoding (video.dll) takes the biggest part, but also the dithering
  423.   ocupies the CPU 20 to 25% of the time. The overhead of the player dimp.exe
  424.   which includes DIVE (palette conversion + resizing + blitting) is minimal.
  425.  
  426.   Secondly I analyzed the PPU when using different dithering techniques:
  427.  
  428.   dither method -> ordered ordered2 gray fs2 fs4 fs2fast hybrid hybrid2 mbordered
  429.   
  430.   dimp.exe         11      13       15   7   6   9       12     10      10
  431.   video.dll        70      64       83   40  33  50      74     60      65
  432.   dither.dll       19      23       2    52  61  41      14     30      24
  433.  
  434.   Here we see big variations in the PPU of the dither.dll module. Fastest is gray-
  435.   dithering which translates luminance values directly to gray shades. fs4-
  436.   dithering delivers good quality but is the slowest. Fastest 8-bit color dithering
  437.   is hybrid while maintaining reasonable quality.
  438.  
  439. Any comments/bug reports/suggestions are appreciated. Please send them to the 
  440. mail-adress mentionned before.
  441.  
  442. Peter Van Geit
  443. 11 juli 1995