home *** CD-ROM | disk | FTP | other *** search
/ POINT Software Programming / PPROG1.ISO / misc / vfwdk / samples / bravado / readme.txt < prev    next >
Text File  |  1993-01-19  |  9KB  |  246 lines
  1. The files in this directory are used to create capture drivers 
  2. based on the Chips and Technologies PC9001A chipset.  These include:
  3.  
  4. Truevision Bravado
  5. Creative Labs Video Blaster
  6.  
  7.  
  8. ========== Modifying this sample driver ===================
  9.  
  10. 1. If you avoid modifying the core message processing
  11.    files (DRVPROC.C, VMSG.C) and isolate your changes to
  12.    CTDEV.C, integration with future updates will be
  13.    easier.
  14.  
  15. 2. Update the VERSION, REVISION, RELEASE fields
  16.    in SAMPLE.RCV, as appropriate, with each build.
  17.    This will ensure our installation utilities are
  18.    able to automatically load the newest version of your
  19.    driver.
  20.  
  21. 3. Change the VERSIONDESCRIPTION field in BRAVADO.RC
  22.    to an appropriate name.  Also change the module 
  23.    name in the .DEF file.
  24.  
  25. 4. In addition to support for the standard DIB formats,
  26.    the sample driver demonstrates how to save data
  27.    in a custom format, in this case the native 
  28.    scaled YUV format found on boards using the 
  29.    PCVIDEO-Phillips encoder chipsets.  This capability will 
  30.    be removed from the final shipping driver and is only 
  31.    provided here as a demonstration.
  32.  
  33. ============= Changes since Final Beta ======================
  34.  
  35. 1. Prevent PCVIDEO from holding the READY line false for 20mS
  36.    if read of frame buffer is attempted before acquisition 
  37.    is completed.  Changed CT_PrivateAcquire(). IMPORTANT!
  38.  
  39. 2. In InStreamISR, changed the logic which determines when
  40.    a new frame can be captured.  This insures that at least
  41.    two vertical sync pulses are received prior to capturing
  42.    the next frame.
  43.  
  44. 3. Updated the VERSIONINFO fields in SAMPLE.RCV.
  45.  
  46. 4. Added code and structure fields which simplify the task
  47.    of combining capture drivers and codecs into a single
  48.    driver. Search for _CODEC_SUPPORT to note the changes.
  49.  
  50. 5. Added support for Base I/O port selection into the 
  51.    configuration dialog box.  On the Bravado, this value 
  52.    can be altered dynamically, but on the Video Blaster, 
  53.    we just report the setting used by PCVIDEO.DLL.  The
  54.    user must use VBSETENV.EXE to set the I/O base for the
  55.    Video Blaster since PCVIDEO.DLL uses the environment
  56.    variable set by this program.
  57.  
  58. ============= Changes since Beta1.0c ======================
  59.  
  60. 1. The VHDR_INQUEUE flag was not being set as frames were
  61.    added to the queue.  To update your driver, search the
  62.    sample code for "VHDR_INQUEUE" and note the appropriate
  63.    changes.
  64.  
  65. 2. In response to the DVM_FRAME message (get a single frame),
  66.    the sample source was not setting dwBytesUsed, dwTimeCaptured,
  67.    or dwFlags in the VIDEOHDR structure.  Note the change to
  68.    the CaptureFrame function in "cap.c".
  69.  
  70.    WORD FAR PASCAL CaptureFrame(LPVIDEOHDR lpVHdr)
  71.    {
  72.      // ...
  73.      // ...
  74.  
  75.      // If you provide compressed data, set dwBytesUsed to
  76.      // the actual size of the compressed image.
  77.  
  78.      lpVHdr->dwBytesUsed = biDest.biSizeImage;
  79.      lpVHdr->dwTimeCaptured = timeGetTime ();
  80.      lpVHdr->dwFlags |= VHDR_KEYFRAME;
  81.  
  82.      return DV_ERR_OK;
  83.    }
  84.  
  85. 3. The speed of the RGB16 capture has been greatly improved (5x?).
  86.    This was accomplished by using a look up table with resulting
  87.    changes in CAP.C, RECT.C, MAPA.ASM, and MAPC.C.  Search for the
  88.    variable "fpYUVtoRGB16" to note the changes.
  89.  
  90. 4. Additional logic has been added to the sample driver to 
  91.    increase robustness.  For example, if the channel is closed
  92.    while streaming capture is being performed, or buffers are
  93.    left in the queue, the channel now refuses to close.  
  94.    Search for "gfVideoInStarted" and "lpVHdrFirst" to note the
  95.    changes.
  96.  
  97. 5. An additional error value has been defined "DV_ERR_PROTECT_ONLY"
  98.    which your driver can return if it only runs in enhanced mode.
  99.    Vidcap will run in either enhanced or standard modes.  Due
  100.    to problems with EMM386, drivers which access memory via linear
  101.    mapping of extended memory in standard mode should return this
  102.    value.  Note the changes in INITC.C:
  103.  
  104.    DWORD FAR PASCAL InitCheckMem( void )
  105.    {
  106.         int j;
  107.         LPSTR lpc;
  108.  
  109.         if ((GetWinFlags() & WF_ENHANCED) == 0)
  110.             return DV_ERR_PROTECT_ONLY;       
  111.         // ...
  112.         // ...
  113.  
  114.         return DV_ERR_OK;
  115.     }
  116.  
  117. 6. The DVM_STREAM_GETPOSITION message was always returning
  118.    0.  Search for "dwTimeStream" in CAP.C to note corrections.  
  119.  
  120. 7. MAX_OUT_CHANNELS is now set to zero in CT.H to reflect the fact
  121.    that the VIDEO_OUT channel is not used in the sample driver.
  122.  
  123.  
  124. ============= Changes since Beta1 =========================
  125.  
  126. 1.  Replaced DV_VM_OPEN, DV_VM_CLOSE, DV_VM_DATA, 
  127.     DV_VM_ERROR, with the generic MM_DRVM_OPEN,
  128.     MM_DRVM_CLOSE, MM_DRVM_DATA, MM_DRVM_ERROR.
  129.  
  130. 2.  The parameters to videoStreamGetError and 
  131.     DVM_STREAM_GETERROR have changed.  
  132.     Vidcap will always call videoStreamGetError
  133.     in the inner capture loop, since some drivers which
  134.     are non-interrupt driven rely on this "wake-up" call.
  135.  
  136. 3.  Added VHDR_KEYFRAME as a flag to the 
  137.     VIDEOHDR.dwFlags field.  Removed VHDR_STARTFRAME
  138.     and VHDR_CONTFRAME flags from the same field.
  139.  
  140. 4.  When receiving DVM_ADDBUFFER, the dwBytesUsed
  141.     field must be set to zero by the driver. 
  142.  
  143. 5.  A dwError field was added to the VIDEO_OPEN_PARMS.
  144.     This allows drivers to return an error code if
  145.     they fail to open.  Vidcap displays the corresponding
  146.     error text in the status bar, giving the user some
  147.     feedback.  Additional error messages are also
  148.     defined in MSVIDEO.H.
  149.  
  150. 6.  Vidcap now allows drop frames to be inserted in the
  151.     video stream if the driver misses frames.  All other
  152.     tools handle drop frames by just continuing to display
  153.     the previous frame for the time slot.  This allows
  154.     capture up to 100fps for all drivers, and removes
  155.     the requirement of defragmenting disks.  The
  156.     "Error: Data rate too high." message no longer appears.
  157.     Additional logic was added to the sample driver 
  158.     (in CAP.C) to (a) return accurate time information 
  159.     in milliseconds of when the frame was captured, and
  160.     (b) ensure that a full frame of video has been 
  161.     captured since exiting the last interrupt.
  162.  
  163. 7.  The YUV to palettized conversion routine has been
  164.     improved to allow capture at 15fps.  Also, the 
  165.     Luma component has been scaled (actually part of
  166.     the YUV look-up table creation process) to brighten
  167.     the image.
  168.  
  169. 8.  The configuration dialog box now prints the name
  170.     of the driver and the version number.
  171.  
  172. 9.  Cleaned-up error handling in low memory conditions.
  173.  
  174. 10. The sample driver writes out uncompressed YUV data.
  175.     This can be used to test installable codecs.
  176.  
  177. ============== Setting up drivers ===========================
  178.  
  179. The Drivers applet in the control panel cannot install
  180. more than one driver of type MSVIDEO.  Either deinstall
  181. an existing driver, or manually edit SYSTEM.INI. 
  182. If you choose to manually edit SYSTEM.INI, you can 
  183. select between any available driver at run time.
  184.  
  185. [Drivers]
  186. msvideo=targa16.drv
  187. msvideo1=testdrv.drv
  188. msvideo2=bravado.drv
  189. msvideo3=vblaster.drv
  190. msvideo4=MYDRVR.DRV
  191.  
  192. Vidcap takes a command line parameter specifying the
  193. index of the driver to use:
  194.  
  195. VIDCAP -d0         (uses targa16.drv)
  196. VIDCAP -d1         (uses testdrv.drv)
  197. VIDCAP -d2         (uses bravado.drv)
  198. VIDCAP -d3         (uses vblaster.drv)
  199. VIDCAP -d4         (uses MYDRVR.drv)
  200.  
  201. ============== Other DLLs required ========================
  202.  
  203. Some of the MSVIDEO drivers use a vendor supplied DLL
  204. to provide low level device control.
  205. The appropriate DLL must be present on the path 
  206. prior to installing or using the driver.
  207.  
  208. Driver                     Support DLL
  209. --------                --------------------
  210. Targa16.drv                none
  211. Testcap.drv                none
  212. Bravado.drv                VW.DLL
  213. VBlaster.drv               PCVIDEO.DLL
  214.  
  215.  
  216. ====== Vidcap drivers and Installable Compressors ===========
  217.  
  218. A significant enhancement in AVI since the previous release
  219. is the ability of all the tools to handle video streams 
  220. in compressed formats.  
  221.  
  222. When writing an AVI file, Vidcap honors the VIDEOHDR.dwBytesUsed 
  223. field, and writes a RIFF chunk of this size.  The FOURCC
  224. biCompression field of the BITMAPINFOHEADER returned
  225. by the driver in response to a DVM_FORMAT message
  226. is written to the AVIStreamHeader.fccHandler field in the file.
  227.  
  228. To display a compressed stream, the installable
  229. compressor interface searches for a codec which can support
  230. the format specified in the AVIStreamHeader.fccHandler.
  231. Depending on the request, the codec either
  232. just decompresses the frame, or can take responsibility
  233. for rendering also.  This allows codecs to be written
  234. which send the compressed image to a hardware decompressor
  235. if one is present, and perform software conversion to a DIB
  236. if hardware is unavailable.
  237.  
  238. Note that the APIs and Messages for Installable Compressors
  239. and Vidcap drivers have been designed so that a single
  240. driver can perform both capture and codec functions.
  241. The VIDEO_OPEN_PARMS.fccType field passed when the driver is
  242. opened contains 'vcap' if a capture channel is requested, and
  243. contains 'vidc' when a codec is opened.
  244.  
  245.  
  246.