VidPlus

Software Development Kit

Version 4.5.0.5

May 22, 1999

Copyright 1994-1999 Brian Reed.  All Rights Reserved.

Table Of Contents

Chapter 1 ……..	Application Programmer Overview
1.1) Overview
1.2) Notes for the Application Programmer
1.3) Program Module Description

Chapter 2 ……..	Programming the high-level VPAPI.DLL
			2.1) VPSIMPLE.C - A sample of simplest usage - C
			2.2) VPAPIMFC.CPP - A sample C++ class interface
			2.3) VPAPI.DLL - Details & Error listing
			2.4) VPAPI.DLL - Function Reference

Appendices ……..	Technical references
			A) Discussion of the DAC registers and routines
B) Overlay Display and Overlay Capture
C) The low-level driver VIDPLUS.SYS

1.1  Application Programmer Overview

This Software Development Kit is intended for programmer implementation of the certain graphics adapters under Windows NT 3.51 and 4.0.  The core program is a Windows NT kernel-mode driver which manages all low-level communications with the adapter.  Also included are a high-level programmers library, sample application source code, and utility programs.

These programs and documentation do not attempt to replace the classic reference manuals for the adapters.  The adapter’s hardware reference manual is highly recommended for understanding the details.  Some familiarity with programming the adapter is helpful.

Device drivers have been improved significantly since the days of DOS popularity, and VIDPLUS.SYS is no exception.  The driver still offers a set of IOCTL primitives (sub-functions) similar to DOS drivers, but it was designed for NT from the ground-up and it's design differs from the original Targa+ driver.

To assist in the development of your end-user application, a library has been programmed to offer a high-level Application Programmer Interface.  This library is VPAPI.DLL, and is the primary programmer interface for VidPlus.  A full function reference is contained in this manual.

The remaining programs include a registry configuration program and utility applications.  Source code for the utilities are included as sample applications.

Getting Down To Work
	
	1) Install VidPlus as described in the installation manual.

	2) Experiment with VPGUI, VPCMD and other sample applications.

	3) Implement a sample application in your development environment.

1.2  Notes for the Application Programmer

April 12, 1999: Version 4.5.0.0:

	Added VP_UserMap() and VP_UserUnmap().  These allow the application direct access to the still-frame display memory.  Usage requires detail knowledge of the operation of the adapter!  Microsoft recommends NOT to architect applications in this way.  I also do not recommend this usage, but with care it can be useful.  The tradeoff is a bit more performance at the risk of letting your pointer math crash your application.  See the new VPDIRECT.C sample for more details.  

Intel has a nice library for image processing.  They call it “IPL”, and I found it at:
http://developer.intel.com/design/perftool/perflibst/index.htm

Here is a shareware DLL with JPG and BMP support.  I have not yet tested it myself.
http://www.smalleranimals.com/imgdll.htm

Also untested:
If you want to access bits, it's best to use DIBs instead of DDB's, because a DDB's data depends on the video mode you're in ( unless you want to write routines for all bit depths ).  You can use this CDib class if you like, it's extremely easy to use, and you can access all image data directly (it's 32 bits color only).  It also has colorkeying, alpha blending, compositing ( add, difference, multiply, screen, etc ) and a lot of other functions.
	http://www.luc.ac.be/~ef00/ebgfx        btw, it's free with source included.
   El Barto (ef00@luc.ac.be)

1.3  Program Module Description

The bulk of the VidPlus SDK is source code for sample applications in a variety of Win32 languages.  First, the two system binaries:

DRIVER\VIDPLUS.SYS:

A true kernel-mode device driver for Windows NT 3.51 and 4.0.  This module handles all communications with the adapter to provide the low-level functionality.  VPDRVAPI.H is one of the master VidPlus include files.

VPAPI\VPAPI.DLL:

A support library for the driver.  This module provides the primary high-level Application Programmer’s Interface.  VPAPI.H is the master VPAPI.DLL header file.

\VPCONFIG:

An end-user application to assist in configuring the registry for VIDPLUS.SYS.  Delphi3 source code.  You might automate the VidPlus registry entries during your own application’s install.

\VPSIMPLE:

VPSIMPLE.C is the simplest possible application in “C”, and demonstrates opening of the VidPlus device plus making a few VPAPI.DLL calls.

\VPGUI:

This is the primary sample application for VidPlus, a GUI based application to demonstrate control of the adapter.  Written in C++ using Microsoft Foundation Classes.  The VidPlus class is in VPAPIMFC.CPP and VPAPIMFC.H.

\VPCMD:

This is a command-line based application to control the adapter.  This is also a primary sample application for VidPlus.  “C” source code.

\VPCAM:

This is a GUI based end-user “Web-Cam” application to demonstrate control of the adapter.  Written in Delphi3, source code is included.  VPAPI.PAS is the Delphi3 class for VidPlus.  This is provided for sample and experimentation only, it is not a refined WebCam application.

\VPVBSAMP:

A small GUI based end-user application to demonstrate control of the adapter.  Source is for Visual Basic 5.0.  See VPAPI.BAS for the DLL import statements.

\VPDIRECT:

Demonstrates direct application access of the adapter’s page frame (still-store) display.  Direct access is not recommended, but with care can be useful.  See the notes within VPDIRECT.C.

2.0  Programming the high-level VPAPI.DLL

For Windows NT, the application programmer uses the Windows API function CreateFile() to open access to a device.  See Win32 documentation for more information about the CreateFile() function. 

The VidPlus sample application VPSIMPLE demonstrates the simplest possible application to open access to the device, and make VPAPI.DLL calls to control the adapter.

The actual device names for VidPlus are in the form “\\.\VidPlusDev1".  In a C string where this slash character is an escape character, the string looks like “\\\\.\\VidPlusDev1".  Devices are numbered 1 through 4.

Packed Color Specifiers

Many VidPlus routines require color data to be packed into a bit-format that is display depth dependent.  Pass a pointer to the color specifier when calling the functions.  The size of the color specifier itself must meet or exceed the current display depth - it is general practice to use a 32-bit variable to hold the color specifier and leave some bits unused for resolutions less than 32-bit.  The routines VP_PackColor and VP_UnpackColor will assist in manipulating 32-bit color specifiers.

* 8-Bit Mode:
Each color specifier is 8 bits long - place them into the lowest 8 bits when using a 32-bit color specifier variable.  Valid values are 0-255 and represent a gray-scale intensity value when the Look-Up-Table is disabled.  When the LUT is enabled, the value is used as an offset into the color table to reference 24-bit RGB colors.

* 16-Bit Mode:
Each color specifier is 16 bits long - place them into the lowest 16 bits when using a 32-bit color specifier variable. Valid values are 0 to 65535 and represent 5 bits each for Red, Green and Blue, along with 1 bit for Overlay.  The bit pattern is: “ORRRRRGG GGGBBBBB”.

* 32-Bit Mode:
Each color specifier is 32 bits long, with each byte representing Alpha, Red, Green and Blue.  The bit pattern is: “AAAAAAAA RRRRRRRR GGGGGGGG BBBBBBBB”.  By default, VidPlus implements an 8-bit alpha channel, and it’s most significant bit can also serve as the overlay bit when the adapter is in Overlay mode.

2.1  Sample program - VPSIMPLE.C

/*    “VPSIMPLE.C”   --  A Win32 command-line application.    */

#include <windows.h>	// Include the usual Windows info.
#include <stdio.h>		// Include the usual prototype for printf.
#include "vpapi.h"		// Include VidPlus headers (VPAPI.H and VPDRVAPI.H).

INT main(INT argc, CHAR *argv[])
{
HDRVR		hDevice[4];	// Make a place for device handles to the VidPlus devices.

  // Put your startup message here.
  printf("\nVPSIMPLE:  Copyright 1996-1998 Brian Reed.  All Rights Reserved.\n");

  // Now open the VidPlus Device the same way as all devices in NT.
  //  * The first parameter represents the actual device name in the form
  //      "\\.\VidPlusDev1", but to get a backslash in C requires double
  //      backslashes, so it ends up looking as shown.
  //  * The rest of the parameters are straightforward, see Win32 help for details.
  //
  hDevice[0] = CreateFile(
	"\\\\.\\VidPlusDev1",			// Specify adapter 0.
	GENERIC_READ+GENERIC_WRITE,	// Read & Write access!
	FILE_SHARE_WRITE,			// Sharable WRITE!
	NULL, OPEN_EXISTING, 0, NULL);		// Regular stuff.

  // If the device was opened OK, use it.  If not, display an error.
  if (hDevice[0] != INVALID_HANDLE_VALUE) {

    // Change the resolution of the adapter under VidPlus control.  Not -required-.
    VP_SetResolution(hDevice[0],		// Use our adapter handle.
		VP_NTSC_512x486,	// Set the resolution,
		VP_DEPTH_2BYTE,	//   depth,
		VP_INTERLACED);	//   and interlace modes.

    // For our simple app, let's make sure we can see the composite video.
    VP_SetLiveSrc(hDevice[0], VP_LIVESRC_COMPOSITE);	// Select our input.
    VP_SetGenlock(hDevice[0], VP_GENLOCK_ON);		// Turn Genlock ON.
    VP_SetLiveMode(hDevice[0]);				// Display to LIVE mode.

     // Close the Device.  Be sure not to forget this!
    CloseHandle(hDevice[0]);
    printf("**OK!\n");
    return 0;

  }
  else {
    printf("**Sorry, cannot open the VidPlus device.\n");
    printf("  Check in ControlPanel | Devices | Vidplus to see the\n");
    printf("  driver status - it should be 'Started'.  If it is not,\n");
    printf("  please see the VidPlus installation documentation.\n");
    return 1;
  }

}

2.2  VPAPIMFC.CPP - C++ Class Interface

VPGUI is a primary user program and programming sample for VidPlus.  It uses Microsoft’s “MFC” class library to implement a Class Interface for the adapter, and is based on their DIBLOOK demo.

Watch the status bar at the bottom of the window for “Hint” descriptions about each toolbar item.  

The VidPlus class interface can be found in VPAPIMFC.CPP and VPAPIMFC.H.  Copy these into your own application.  See MAINFRM.CPP for more details, especially:

Declaring instances of the class:
	CVidPlus VidPlus[4];    // This application can use up to 4 devices.

Then VidplusInitHardware() demonstrates opening a device using the OpenDevice() member function:
	VidPlus[0].OpenDevice("\\\\.\\VidPlusDev1") ;

Also, VidplusCloseDevice() demonstrates closing a device with the CloseDevice() member functions:
	VidPlus[0].CloseDevice();

When open, you can call device functions like this:
	VidPlus[0].SetLiveMode();

2.3  VPAPI.DLL Details

VPAPI.DLL is based in good part around the Truevision library TARGADLL.DLL.  If you have the classic Targa+ SDK, you may wish to consult the TKIT\TARGA directory for the source to TARGADLL.  VPAPI incorporates many bug fixes to that old code and expands upon it’s functionality, but it might still be helpful in understanding VPAPI design.

VPDRVAPI.H and VPAPI.H are the master include files.

Common function return values (from VPAPI.H):

enum VP_ERR {
  VP_ERR_NOERR		=   0,	// SUCCESSFUL FUNCTION CALL	// 0 to -12 are historic
  VP_ERR_INVALIDHDRVR	=  -1,	// Was _ERR_NOSUCHBOARD		//  TARGADLL.DLL
  VP_ERR_MEMALLOCERR	=  -2,	// Not enough memory!			//   error values.
  VP_ERR_UNUSED3		=  -3,	// Unused (_ERR_DRVNOTAVAIL)
  VP_ERR_DRVRERR		=  -4,	// Error calling driver
  VP_ERR_UNUSED5		=  -5,	// Unused (_ERR_MEMFREERR)
  VP_ERR_UNUSED6		=  -6,	// Unused (_ERR_NOTARGA)
  VP_ERR_READFAIL		=  -7,	// Error from reading a row buffer
  VP_ERR_INVALIDMODE	=  -8,	// Incorrect mode
  VP_ERR_WRITEFAIL		=  -9,	// Error from writing a row buffer
  VP_ERR_INVALIDPICHDR	= -10,	// Picture header is not valid
  VP_ERR_FILEIOERR		= -11,	// Error during file IO
  VP_ERR_EMPTYSAVERECT	= -12,	// Empty rectangle in VP_PutPic
  VP_ERR_PARAMETER	= -13,	// Invalid parameter
  VP_ERR_NOTDIB		= -14,	// Could not find or recognize DIB bitmap
  VP_ERR_CREATEPAL	= -15,	// Error creating palette
  VP_ERR_CREATEDDB	= -16,	// Error creating DDB
  VP_ERR_CLIPBUSY		= -17,	// Clipboard is busy
  VP_ERR_NOCLIPFORMATS	= -18,	// Can't find DIB or DDB during paste operation
  VP_ERR_CANNOTOPEN	= -19,	// Cannot open file
  VP_ERR_CANNOTREAD	= -20,	// Cannot read file
  VP_ERR_CANNOTWRITE	= -21,	// Cannot write file
};

2.4  Function list for VPAPI.DLL

VP_SetResolution	- Reset the adapter to a specified XY size, pixel depth, and interlace mode.
VP_GetBoardInfo	- Copy adapter information from the driver.
VP_ReadEEPROM	- Copy the EEPROM data to an array provided by the programmer.
VP_ReadAll	- Read all adapter registers into a data structure.  (useful for app debugging).
VP_SetDisplayOnOff	- Enables and disables adapter output.
VP_GetErrorString	- Retrieve the text message for a specified error value.

VP_SetDispMode	- Set to Display (still-frame) mode.
VP_SetBLiveMode	- Set to Border Live mode.
VP_SetOverMode	- Set to Overlay mode.  This overlays live and still-frame based on a 1-bit overlay value.
VP_SetLiveMode	- Set to Live mode.
VP_GetDisplayMode	- Get current dispMode register setting: Display, BLive, Overlay or Live.
VP_SetDisplayMode	- Set current dispMode register setting per input parameter: Display, BLive, Overlay or Live.
VP_SetTARGAOverlay	- Write to register F5 of DAC2.  Duplication of WriteDAC() functionality.
VP_SetBlndMode	- Initialize registers for Blend mode.  Activates 8-bit alpha plane in 32-bit mode.
VP_SetChromakey	- Initialize registers for Chroma Key mode.  Used for ‘blue-screen’ composite effect.
VP_ChromaCapture	- Perform a capture of the composite chroma key image. (not yet tested.)
VP_SetOverlayCapture	- Initialize registers for Overlay capture.
VP_OverlayCapture	- Perform a capture of the composite overlay image.
VP_SetLiveMixGain	- Adjust gain of alpha control signal.  Primarily used to increase chroma key sensitivity.
VP_SetLiveMixZero	- Adjust zero point of  the alpha control signal.  Primarily used to ‘tune’ chroma keying.
VP_SetOVLLevel	- Controls overlay mix between live video and still-frame.
VP_SetNotOVLLevel	- Controls overlay mix between live video and still frame.

VP_SetLivePort	- Select from 4 Live Port Mux inputs including Live, VRAM word 0 & 1, and border color.
VP_SetBufferPort	- Select the input to Mixer Buffer Port.

VP_SetPage	- Switch to another page of still-frame image memory on the adapter.
VP_GetPage	- Determine which page the adapter is currently displaying in the still-frame.
VP_GrabFrame	- Grab the next full frame of video (both fields).
VP_GrabField	- Grab the next even or odd field.
VP_GetVidLoss	- Determine if a valid input signal is present on the selected live source.
VP_SetGrab	- Turn the capture bit on and off.  (for internal use.)
VP_GetField	- Determine which video field is currently being displayed.  (for internal use.)
VP_VWait	- Loop until the next vertical sync signal.  (for internal use.)

VP_SetRGB	- Set the RGB bit on.  Used in conjunction with the SVideo bit.  Also see VP_SetLiveSrc.
VP_SetSVideo	- Set the SVideo bit on.  Used in conjunction with the RGB bit.
VP_SetLiveSrc	- Select input video source (Composite, S-Video, RGB)
VP_GetLiveSrc	- Get input video source selection.
VP_SetVCRorCamera	- Select type of input source.
VP_GetVCRorCamera	- Get the current input source type.

VP_SetZoom	- Set the zoom multiplier for the still-frame.
VP_GetZoom	- Get the current zoom setting.
VP_SetPanUL	- Set the X and Y pan position for the still-frame with origin at the upper-left of the screen.
VP_SetPan	- Set the X and Y pan position for the still-frame.
VP_GetPan	- Get the current X and Y pan position.

VP_SetInterlace	- Set the adapter to interlace or non-interlace video mode.
VP_GetInterlace	- Get the current interlace state.
VP_SetGenLock	- Set the Genlock state.
VP_GetGenLock	- Get Genlock setting.

VP_SetIRE	- Set the IRE black level.
VP_GetIRE	- Get the IRE state.

VP_SetHorizPhase	- Set current Horizontal Phase setting.
VP_GetHorizPhase	- Get current Horizontal Phase setting.
VP_SetSCPhase	- Set current Sub-Carrier Phase setting.
VP_GetSCPhase	- Get current Sub-Carrier Phase setting.

VP_WriteDAC	- Write to the digital-analog-converter registers.
VP_ReadDAC	- Read the last values written to the DAC registers.
VP_WritePLL	- Write to the phase-lock-loop registers.
VP_SetLUTMode	- Turn DAC LUT’s on or off.
VP_GetLUTMode	- Get current DAC LUT’s state (enabled/disabled).
VP_WriteLUT	- Set the DAC Look-Up-Tables to values supplied by the programmer.
VP_ReadLUT	- Copy data from the DAC LUT’s to an array supplied by the programmer.
VP_SetGamma	- Write a Gamma curve to the DAC lookup-tables.

VP_SetContrast	- Adjust the DAC register to affect contrast.
VP_GetContrast	- Read the last values written to this DAC register.
VP_SetSaturation	- Adjust the DAC register to affect saturation.
VP_GetSaturation	- Read the last values written to this DAC register.
VP_SetHue	- Adjust the DAC register to affect hue.
VP_GetHue	- Read the last values written to this DAC register.
VP_SetBrightness	- Adjust the DAC register to affect brightness.
VP_GetBrightness	- Read the last values written to this DAC register.

VP_SetConRegister	- Set the contents of the Contrast register.  These are separate from the DAC registers!
VP_GetConRegister	- Get the contents of the Contrast register.
VP_SetHueRegister	- Set the contents of the Hue register.
VP_GetHueRegister	- Get the contents of the Hue register.
VP_SetSatRegister	- Set the contents of the Saturation register.
VP_GetSatRegister	- Get the contents of the Saturation register.

VP_CopyRect	- Copy a rectangular area from one location in the still-frame to another location.
VP_CopyClipboard	- Copy adapter still-frame image to the Windows clipboard.
VP_PasteClipboard	- Paste image on the Windows clipboard to the adapter still-frame.
VP_DIB2Disp	- Copy a Device-Independent-Bitmap to the adapter still-frame.
VP_Disp2DIB	- Copy the adapter still-frame image to a DIB.
VP_CreateDIB	- Create a Windows Device-Independent-Bitmap for use.
VP_DestroyDIB	- Destroy a DIB created with VP_CreateDIB.

VP_GetRow	- Read a row of pixels from the adapter still-frame to a programmer array.
VP_PutRow	- Write a row of pixels to the adapter still-frame from a programmer array.
VP_PutRowEx	- Special version of VP_PutRow for internal purposes (font support).
VP_GetPix	- Read a pixel from the adapter still-frame image.  Calls VP_GetRow.
VP_PutPix	- Write a pixel to the adapter still-frame image.  Calls VP_PutRow.
VP_GetPic	- Read a TGA image from disk and display in the still-frame.
VP_PutPic	- Save the still-frame image to a TGA file.

VP_PackColor	- Combine color components into a packed color value.
VP_UnpackColor	- Extract color components from a packed color value.
VP_SetMask	- Set the pixel mask.  Used to mask specific bits when writing to pixel memory.
VP_SetBorderColor	- Set the color of the still-frame border.

VP_DrawText	- Draw text to the adapter using Windows TrueType fonts.
VP_Line	- Draw a line of specified color and width.
VP_Rectangle	- Draw a hollow rectangle of specified color and line width.
VP_FillRect	- Fill a rectangular area in the still-frame to a specified color.
VP_Erase	- Clear the current still-frame page to a color.
VP_Curve	- Draw a smooth curve from an array of point data.
VP_Ellipse	- Draw a hollow ellipse.

VP_outp	- Outputs a byte to a direct register.
VP_inp	- Reads a byte from a direct register.
VP_outpw	- Outputs a 16-bit word to a pair of direct registers.
VP_inpw	- Reads a 16-bit word from a pair of direct registers.
VP_IR_outpw	- Outputs a 16-bit word to an indirect register pair.
VP_IR_inpw	- Reads a 16-bit word from an indirect register pair.

VP_UserMap	- Allows the application to obtain a virtual address to the display memory.
VP_UserUnmap	- For application cleanup after using the pointer from VP_UserMap.

VP_GraphReset	- Re-initializes the DLL.
	  (For internal use, not used for application programming.)
VP_CheckResolution	- Re-synchronizes driver variables with the adapter registers.
	  (For internal use, not used for application programming.)

VP_SetVGAOverlay	- Change VGA overlay parameters.  
	  (single-monitor usage is not provided by VidPlus.)
VP_GetVGAOverlay	- Get the current VGA overlay setting.
	  (single-monitor usage is not provided by VidPlus.)

VP_DIB2Disp

Copy a Windows Device-Independent-Bitmap to the frame-buffer.  The copy is placed at the specified X & Y position on the adapter.  The DIB may be less or greater than full-screen size, but it must be 8 or 24 bits in depth.  There are some special cases where simple RGB copy is not used:

•	When copying an 8-bit DIB that has no color palette, the values are assumed to be gray-scale.
•	When copying an 8-bit DIB to 8-bit display mode and a color palette exists in the DIB, the first 256 entries in the palette are loaded to the Look-Up-Table on the adapter and the LUT mode is set to ON.
•	When copying an 8-bit DIB to 16 or 32-bit display mode, the palette is used to determine each RGB color.
•	When copying a 24 bit DIB to 8-bit display mode, the RGB pixel values are averaged to create a gray-scale image.  

Function prototype and parameters:

INT VPFUNC VP_DIB2Disp(HDRVR hDevice, HDIB hDIB, enum VP_BLIT BlitOP, INT x, INT y);

	hDevice		Handle to the already opened VidPlus device.

	hDIB		Handle to a pre-allocated DIB. The DIB must be in the Windows 3.0 format and the header,
			pixel data, and palette data (if any) must be contiguous.

	BlitOP		Specifies type of transfer.
			0 = Copy to Display.  VP_BLIT_SRCCOPY.

	x		Specifies the left coordinate of the display area to copy to.  This will most often be 0.

y	Specifies the bottom coordinate of the display area to copy to.  This will most often be 0, but can be used to copy to display pages greater than page 0.  In interlaced display modes, multiply the desired page number by 512 for the Y value.

Function returns:
VP_ERR_NOERR: Operation successful.
Less than 0 indicates failure:
	VP_ERR_INVALIDHDRVR: Invalid hDevice parameter.
	VP_ERR_PARAMETER: hDIB is NULL.
VP_ERR_MEMALLOCERR: Unable to lock DIB memory.
VP_ERR_NOTDIB: No DIB supplied, or unsupported format.

Registers affected:
	HBNK, 0x0B.
	MODE1, 0x0C.	mem (bit 0)

Function sample:
	HDRVR hDIB;
hDIB = VP_CreateDIB(VP_DIB_DEPTH_24BIT, 512, 486); 	// Pre-allocate a Windows DIB
if (hDIB) {
// (Put pixels in the DIB here.)
// Now copy DIB to the Display and destroy the DIB
retval = VP_DIB2Disp(hDevice, hDIB, VP_BLIT_SRCCOPY, 0, 512 * VP_GetPage(hDevice));
VP_DestroyDIB(hDIB);
	}

See also:
VP_CreateDIB, VP_DestroyDIB, VP_Disp2DIB, VP_CopyRect, VP_CopyClipboard, VP_PasteClipboard

VP_GrabFrame

This will grab a complete frame consisting of an even and an odd field.

Function prototype and parameters:

INT VPFUNC VP_GrabFrame(HDRVR hDevice);

	hDevice		Handle to the already opened VidPlus device.

Function returns:

VP_ERR_NOERR: Operation successful.
Less than 0 indicates failure:
	VP_ERR_INVALIDHDRVR: Invalid hDevice parameter.

Registers affected:

	Direct register VP_DREG_D, MODE2.  	Bit 6: capture

Function sample:

	VP_GrabFrame(hDevice);		// Grab a complete frame (2 fields).

See also:

VP_GrabField

VP_PutPic

Save an area of the display buffer to a .TGA file.  The file will be saved in the specified pixel depth.

* If the adapter is in 8-bit mode, the file is saved as a gray-scale image - no color map.

Function prototype and parameters:

INT VPFUNC VP_PutPic(HDRVR hDevice, PCHAR fn,
			enum VP_TGA_DEPTH savedepth,
			enum VP_TGA_COMPRESSION savecompression,
			INT x1, INT y1, INT x2, INT y2);

	hDevice		Handle to the already opened VidPlus device.

	fn		Filename.  Null-terminated string.

	savedepth	Number of bytes per pixel in the destination TGA file.
				VP_TGA_DEPTH_1BYTE = 1
				VP_TGA_DEPTH_2BYTE = 2
				VP_TGA_DEPTH_3BYTE = 3
				VP_TGA_DEPTH_4BYTE = 4

	savecompression	Specify non-compressed or compressed TGA file save.
				VP_TGA_UNCOMPRESSED = 0
				VP_TGA_COMPRESSED = 1

	x1		Specifies the left coordinate of display area to save.

	y1		Specifies the bottom coordinate of display area to save.

	x2		Specifies the right coordinate of display area to save.

	y2		Specifies the top coordinate of display area to save.

Function returns:
VP_ERR_NOERR: Operation successful.
Less than 0 indicates failure:
	VP_ERR_INVALIDHDRVR: Invalid hDevice parameter.
	VP_ERR_CANNOTOPEN: Cannot open file.
VP_ERR_FILEIOERR: Unable to write data to file.  (Out of disk space?)

Registers affected:
	LBNK, 0x0A.
	MODE1, 0x0C.	mem (bit 0)

Function sample:
	retval = VP_PutPic(hDevice, “testfile.tga”,
		VP_TGA_DEPTH_4BYTE, VP_TGA_UNCOMPRESSED,
		0,0, 511,485);

See also:
VP_GetPic