software reference manual - prosoft.rud0%a0%d1�%d0%ba%d0%be%d… · required to develop overlay...

SOFTWARE REFERENCE

MANUAL

AVC2000-V Windows CE Overlay SDK

Document version: A.04

Definitions

AMP and Advanced Micro Peripherals are the trading names for Advanced Micro Peripherals Inc. and Advanced Micro Peripherals Ltd.

Disclaimer

This document contains information on a new product. Specifications and information herein are subject to change without notice.

AMP reserves the right to make changes to any products herein to improve functioning and design. Although the information in this

document has been carefully reviewed and is believed to be reliable, AMP does not assume any liability arising out of the application

or use of any product or circuit described herein. Nothing in this document is to be taken as a license to operate under or a

recommendation to infringe any patents.

AMP does not recommend the use of any of its products in life support applications wherein a failure or malfunction of the product

may directly threaten life or injury. The user of AMP products in life support applications assumes all risk of such use and indemnifies

AMP against all damages. All information contained in this document is proprietary to AMP and may not be reproduced or disclosed

to any third parties without the written consent of AMP.

The information contained in this document has been carefully checked and is believed to be reliable. However, Advanced Micro

Peripherals Ltd (AMP) makes no guarantee or warranty concerning the accuracy of said information and shall not be responsible for

any loss or damage of whatever nature resulting from the use of, or reliance upon, it. AMP does not guarantee that the use of any

information herein will not infringe upon the patent, trademark, copyright, or other rights of third parties, and no patent or other

license is implied hereby

AMP reserves the right to make changes in the products or specifications, or both, presented in this document at any time and

without notice.

Trademarks

Tiny486, Tiny486, Tiny586DX, Tiny786LP, Mobile786EBX, Tiny886, TinyLX, VAC104, VAC104plus, The Embedded Video Experts are trademarks of Advanced Micro Peripherals.

All other trademarks recognized.

Revision History

Document version Date Comments Approved

A.03

A.04

12th January 2007

24th June, 2009

Contact address updated

Updates to format

GM

Advanced Micro Peripherals operates a company-wide

quality management system, which has been certified by

QMS International plc as

compliant with ISO9001:2000

AVC2000 Windows CE Overlay SDK Software Reference Manual

© 2009 Advanced Micro Peripherals

Document version A.04 3

Contents

1: Introduction ............................................................................................. 4

2: Using the SDK .......................................................................................... 5

SDK Variables .................................................................................................................................................. 6

3: Software Installation ............................................................................... 7

Installing the Driver .......................................................................................................................................... 7

Configuring the Driver ...................................................................................................................................... 8

Initial Testing .................................................................................................................................................... 9

4: Example Application............................................................................... 10

Re-Building the Example Application .............................................................................................................. 11

Application Operation...................................................................................................................................... 11

5: Exported Functions (API) ...................................................................... 12

Initialization Functions.................................................................................................................................... 12

Control Functions ........................................................................................................................................... 18

Capture Functions.......................................................................................................................................... 24

Input Viewport functions ................................................................................................................................. 30

Configuration Functions ................................................................................................................................. 33

6: Function Index ....................................................................................... 58

A: Contacting AMP ...................................................................................... 59



1:

Introduction

The Windows CE SDK for the AVC2000-V frame grabber provides all that is required to develop overlay and capture applications for the AVC2000 under Windows CE 5.0. Currently overlay is supported using DirectX and suitable Direct Draw display drivers are a requirement. Not all display drivers are suitable; compatibility can be checked using the standard CE direct draw sample “mosquito”. If the “mosquito” application can be run successfully the AVC Overlay SDK will work with the display driver. The SDK also provides support for capturing single frames as bitmaps.

The SDK consists of the following components

SDK compiled as a static library

AVC2000 driver supplied as a DLL

Example applications (binary and source)

API Documentation (this document)

The AVC2000 driver supplied as part of this SDK supports both the NTSC and PAL video standards at resolutions up to 640x480. The supported output color formats are RGB15, RGB16, and YUY2.

The example application is supplied in binary and source form, and gives a rudimentary demonstration of the functions of the SDK.

This document as well as providing the complete API listing also provides instructions on including the AVC driver into the CE image, using the SDK library, and a discussion of the example application.



2:

Using the SDK

Using the SDK is a simple manner of linking the static library into the end application and then including the required header files in all application source modules that wish to make use of SDK functions. All application source modules wishing to use the SDK library must include the following two header files

avcsdk.h avc2000.h

The applications must link the SDK library, avclib.lib, into the application at compile time. Including the SDK library to be linked into the application is a simple matter of adding the avclib.lib to the object/library modules section of the project settings. An example Platform Builder project is supplied that demonstrates how to include the library in an application.

2: Using the SDK AVC2000 Windows CE Overlay SDK Software Reference Manual


Document version A.04

2

6

SDK Variables

The SDK features a number of variables that are used internally by the library. A complete list of these variable is given below, note that the values of these variables should not be altered.

VARIABLE DESCRIPTION LPDIRECTDRAW4 g_pDD DirectDraw object

LPDIRECTDRAWSURFACE4 g_pDDSPrimary

DirectDraw pointer to primary surface.

LPDIRECTDRAWSURFACE4 g_pDDSOverlay;

DirectDraw pointer to overlay surface.

LPDIRECTDRAWSURFACE4

g_pDDSOverlayBackBuffer

DirectDraw pointer to the overlay surface

back buffer.

DWORD g_dwUpdateFlags; Update flags for overlay surface.

DDOVERLAYFX g_ovfx; DirectDraw overlay FX structure, used for

the color key capabilities

DDCAPS g_ddcaps; Direct draw capabilities of the display driver.

HRESULT g_hRet; Global Result variable. The value of this

variable is returned using AVC_GetLastError

CapParams *avccap Pointer to internally allocated and managed

proprietary structure.



3:

Software

Installation

This section describes the contents of the Windows CE AVC2000 Overlay SDK Software Package. The software package provides the following directory structure: apps\ - Example application source. docs\ - Software and Hardware reference manuals drv\ - Binary driver, applications, and required configuration files. inc\ - Include files for the library lib\ - Compiled library

Installing the Driver

To use the driver in a Windows CE5 image the driver must be installed into the CE catalog on the development system. To install the driver into the CE catalog a simple install script, “install. bat” is provided in the drv\ directory of the supplied package. This script requires that the _WINCEROOT environment variable is valid to be able to install the driver into the CE catalog. This environment variable can be either manually defined using “set” or a build

window opened from within platform builder (Build OS Open Release Directory) which will have this variable defined. Once the install. bat file has completed, refresh the CE Catalog to see the AVC2000 component. The

3: Software Installation AVC2000 Windows CE Overlay SDK Software Reference Manual



3

8

component is placed in the catalog at Third Party Device Drivers AVC2000. The driver is added to the component the same way as any other catalog member. After adding the component the project must be built to include support for the AVC2000 in the image.

Configuring the Driver

Before an image can be built the image must be configured to reserve a memory buffer for the AVC2000 to use as a frame store. This buffer must be reserved in the config.bib and cannot conflict with any other region. This buffer can start at any value chosen by the system designer and its size is dependent on the desired capture size. The calculation for working out the required size is as follows: BUFFER SIZE = 24576 + (width * height * 2) * 2 where,

width is the maximum desired capture width height is the maximum desired capture height For example when performing a capture @ 640x480 the calculation is as follows BUFFER SIZE = 24576 + (640 * 480 * 2) * 2 = 1253376 = 0x132000 The starting location can be chosen at will from the available space. An example config.bib file is included for reference.

AVCBUF 80220000 00132000 RESERVED

This reserves sufficient memory to allow for 640x480 @ 16bpp capture. Note that in the example given the RAMIMAGE and RAM regions have been moved (by editing the config.bib file) to prevent a conflict.

NK 80360000 009E0000 RAMIMAGE RAM 80D40000 00EC0000 RAM

These are the default values. The config.bib file can be accessed by selecting the “Parameters” tab of the workspace pane and expanding the Hardware Specific files section.

3: Software Installation AVC2000 Windows CE Overlay SDK Software Reference Manual



3

9

The driver needs to be made aware of the location of the frame buffer and this is achieved via the CE registry. The driver is supplied with a suitable .reg file that will configure the card to use a buffer as outlined in the example above. If this buffer is at an alternate location then the registry entries created by the driver component must be amended. This can be done as follows: On the workspace pane, select the “fileview” tab. Expand “projects”, then “amp_avc2000” and finally “Parameter Files”. Double click on “AMP_AVC2000.reg” – this is the registry definitions for the AVC2000 driver. At the end of the file is the card definition section:

[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\AVC2000\0000] "BufferBase"=dword:00220000 "BufferSize"=dword:00132000

The values given for BufferBase and BufferSize should correspond to those in the config.bib. The BufferSize should be exactly the same as that reserved whilst the BufferBase should be identical bar the high bit, i.e. 80220000 becomes 00220000 This concludes the steps required to include the AVC2000 driver in a CE image. The image can now be built and tested.

Initial Testing

To test the operation of the driver using the supplied example application make sure a video source is connected to the AVC2000 as per instructions in the AVC2000 hardware reference manual. The example application, “avcdx”, will have been included in the image automatically and can be found in the /windows/ directory. If using windows explorer to find the file it will be necessary to display hidden and operating system files.



4:

Example

Application

The SDK is supplied with a sample application that demonstrates the use of the documented functions in a simple application to overlay a video window on to the primary display. The sample application uses DirectX and as such using this application requires that the test CE image includes DirectX support including a DirectDraw driver capable of providing Overlay surfaces. The application is terminated by pressing either „F12‟ or „ESC‟. The complete list of keyboard functions is given below:

Key Effect

A Increase brightness

Z Decrease brightness

S Increase contrast

X Decrease contrast

D Increase U component saturation

C Decrease U component saturation

F Increase V component saturation

V Decrease V component saturation

G Increase hue change

B Decrease hue change

W Windowed mode display

T Fullscreen mode display

U Select first composite input

I Select second composite input

O Select S-Video input

P video “pause”

F12 Exit

ESC Exit

4: Example Application AVC2000 Windows CE Overlay SDK Software Reference Manual



3

Re-Building the Example Application

The example application is provided with a Windows CE 5.0 project file that can be used to rebuild the project from within the platform builder environment. It may be necessary to update the location of the SDK library to allow the linker to locate it. The library location is set in the project settings, link tab.

Application Operation

The basic process for implementing an overlay application using the AVC2000 SDK is described below. 1. Initialise the SDK via a call to AVC_InitSDK

2. Create the application window and perform other initialisation required for

the application.

3. Initialise the DirectX components of the SDK via a call to AVC_InitDX.

4. Configure the input capture dimension using AVC_SetInputViewport.

5. Configure the color-key of the overlay surface using AVC_SetColorKey

6. Configure the output using AVC_OutputWindowed .

7. Configure the Input Video format with AVC_SetInputFormat.

8. Program the video capture engine via AVC_Restart .

9. Enable the capture engine using AVC_EnableCapture

This will cause a video window to be created that will display the output of the capture engine.

The process above is a general method, for further explanation of the operation of the example application, consult the source code.



5:

Exported

Functions (API)

The following sections document all of the functions provided by this SDK.

Initialization Functions

AVC_InitSDK

int AVC_InitSDK (void)

The AVC_InitSDK function performs basic initialization of the SDK and the AVC2000 hardware. This should be the first function called from the SDK by an Application.

Returns

The return value is one of the following.

Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE The SDK failed to initialise. AVC_ERR_MEMORY The SDK was unable to allocate the memory required

as a buffer for the AVI capture. AVC_ERR_LOADING_DRI The AVC2000 Driver could not be loaded.

5: Exported Functions (API) AVC2000 Windows CE Overlay SDK Software Reference Manual



A

VER AVC_ERR_NOTFOUND The AVC2000 Hardware was not found in the system.


Comments

This must be the first function called by the application from the SDK, no other functions can be called until this function has successfully returned.

See also

AVC_CloseSDK




A

AVC_CloseSDK

int AVC_CloseSDK (void)

The AVC_CloseSDK function is used to close the SDK and should be the last SDK function called by an application.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_ERR_NOTINITIALISED The SDK has not been initialised and

therefore does not need to be closed.

Comments

After this function has been called library functions cannot be called again until AVC_InitSDK() function has been called and successfully returned.

See also

AVC_InitSDK




A

AVC_InitDX

int AVC_InitDX (hWnd, hInstance)

HWND hWnd; /* Main Window Handle */

HINSTANCE hInstance; /* Instance Handle */

The AVC_InitDX function performs further initialisation of the SDK with particular reference to DirectX. This function must be called if the overlay functionality of the SDK is to be used.

Parameter Description hWnd hInstance

Main window handle Instance handle

Returns

The return value is one* of the following.

Value Description

AVC_SUCCESS The function completed successfully.

AVC_FAILURE An error occurred and the function failed.

AVC_ERR_NOTINITIALISED The SDK had not been initialised.

AVC_ERR_NOWINDOW The hWnd parameter passed in the function call was

NULL.

AVC_ERR_DDRAWCANNOTCREATE The SDK failed to Initialise DirectDraw. For further

error information call AVC_GetLastError().

AVC_ERR_DDRAWQUERYINTERFACE The SDK was unable to get an interface to the

DirectDraw object. For further error information call

AVC_GetLastError().

AVC_ERR_DDRAWSETCOOPLEVEL The SDK was unable to correctly get the required

mode. For further error information call

AVC_GetLastError().

AVC_ERR_DDRAWCREATEPRIMARY The SDK was unable to get a pointer to the primary

display surface. For further error information call

AVC_GetLastError().

AVC_ERR_DDRAWGETCAPS The SDK was unable to get the DirectDraw driver

capabilities. For further error information call

AVC_GetLastError().




A

AVC_ERR_DDRAWNOOVERLAY The DirectDraw display driver does not support

overlay surfaces which the SDK requires. For further

error information call AVC_GetLastError().

AVC_ERR_DDRAWOVERLAY The DirectDraw display driver does not support

overlay surfaces in one of the color spaces supported

by the AVC2000 driver. For further error information

call AVC_GetLastError().

Comments

See also

AVC_GetLastError




A

AVC_CustomInit

int AVC_CustomInit (bInit)

BOOL bInit; /* initialised state */

The AVC_CustomInit function is used to set the initialised state of the SDK. This function is only required when not using the AVC_InitDX function to initialise the SDK and is provided to allow for custom initialisation routines to be developed if they are required. This function sets internal library flags to bypass the checking that all SDK functions do to verify that the SDK is correctly initialised.

Parameter Description bInit When TRUE this causes the internal initialised flags to be set in

order to bypass the status checking that all SDK functions perform on entry.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_ERR_NOTINITIALISED The SDK has not been initialised to a point

where this function can be called.

Comments

This function is provided only to allow custom initialisation routines to be developed; there should be no need to call this function in normal circumstances.




A

Control Functions

AVC_Restart

int AVC_Restart (uMode)

USHORT uMode; /* capture mode */

The AVC_Restart function restarts the driver engine and is used to update any changes made to the configuration.

Parameter Description uMode Capture mode. This can take one of three variables and the choice

here controls how the AVC2000 and the driver operate.

Parameter Description AVC_MODE_OVERLAY In this mode, the driver writes directly to

the DirectDraw overlay surface and uses a callback to indicate whenever the surface is ready to be shown. Back buffers are used to prevent tearing. In this mode a callback function must be registered using AVC_RegisterOverlayCallback() before calling AVC_Restart. AVC_InitDX automatically registers a callback function to satisfy this requirement.

AVC_MODE_CAPTURE In this mode, the driver uses a callback function to indicate whenever new capture data is available. This can be used to provide a stream of captured image data to the application for processing. In this mode a callback function must be registered using AVC_RegisterCallback() before calling AVC_Restart. AVC_InitDX automatically registers a callback function to satisfy this requirement.

AVC_MODE_SINGLE In this mode, the driver waits for the GrabBuffer function to be called manually to grab a single frame.

Returns





A

Value Description

AVC_SUCCESS

The function completed successfully.

AVC_ERR_NOTINITIALISED The SDK has not been initialised to a point where this function can be called.

AVC_NO_CALLBACK The AVC Driver requires a callback to be registered if the capture mode is set to AVC_MODE_CAPTURE. This error is produced when the AVC driver has been restarted in AVC_MODE_CAPTURE before a callback has been registered with the driver.

Comments

See also

AVC_RegisterCallback AVC_RegisterOverlayCallback




A

AVC_RegisterCallback

int AVC_RegisterCallback ((*UserCallback)(void))

void (*UserCallback)(void); /* pointer to function to be called whenever video data is ready */

The AVC_RegisterCallback function is used to register a user supplied function with the driver that is called whenever a complete frame

Parameter Description (*UserCallback)(void) Function pointer for the required function to be called

whenever video data is available.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed. AVC_ERR_NOTINITIALISED The SDK has not been initialized to a point


Comments

The function registered by this function is only called when in AVC_MODE_CAPTURE mode.




A

AVC_RegisterOverlayCallback

int AVC_RegisterOverlayCallback (*(UserCallback)(void))

void *(UserCallback)(void); /* pointer to function to be called whenever video data is ready*/

The AVC_RegisterOverlayCallback function is used to register a user supplied function with the driver that is called whenever Parameter Description (*UserCallback)(void) Function pointer for the required function to be called

whenever video data is available.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed. AVC_ERR_NOTINITIALISED The SDK has not been initialised to a point


Comments

The function registered by this function is only called when in AVC_MODE_OVERLAY mode. The video data is placed in the buffers passed to AVC_SetPhysicalBuffers. To find out which buffer is valid call AVC_GetValidBuffer




A

AVC_SetPhysicalBuffers

int AVC_SetPhysicalBuffers (*bpBuffer1, *bpBuffer2)

BYTE *bpBuffer1; /* Pointer to buffer 1 */

BYTE *bpBuffer2; /* Pointer to buffer 2 */

The AVC_SetPhysicalBuffers function programs the overlay engine to capture into the given buffers. Parameter Description *bpBuffer0 Pointer to buffer1. This MUST be a contiguous block of

memory. *bpBuffer1 Pointer to buffer2. This MUST be a contiguous block of

memory. This can have the same value as bpBuffer2.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed.

Comments

This function does not lock the buffers. To prevent page faults this should be done before calling this function using the Windows CE API call LockPages. DirectDraw surfaces in video memory do not need locking.




A

AVC_GetValidBuffer

int AVC_GetValidBuffer (void)

The AVC_GetValidBuffer function returns the current valid buffer.

Returns

The return value is a zero based index of the current valid buffer.

Comments

This function should be called from the overlay callback to find out which buffer has been filled with valid data.




A

Capture Functions

AVC_EnableCapture

int AVC_EnableCapture (bEnable)

BOOL bEnable; /* enable capture */

The AVC_EnableCapture function is used to enable the capture engine of the driver. Parameter Description bEnable Boolean value controlling whether the capture is enabled. If

TRUE capture is enabled, if FALSE capture is disabled.

Returns


Value Description



Comments




A

AVC_GrabFrame

int AVC_GrabFrame (*buffer)

char *buffer; /* pointer to buffer */

The AVC_GrabFrame function is used to grab a single video frame to a buffer. If this function is called with a NULL pointer it will return the size of the required buffer. Parameter Description *buffer Buffer pointer. If null, this function returns the size of the

buffer required for the current capture settings.

Returns

The return value is either the size of the required buffer (see above) or one of the following.

Value Description



Comments




A

AVC_SaveFrame

int AVC_SaveFrame (lpFileName)

LPCTSTR lpFileName; /* filename */

The AVC_SaveFrame function is used to save a single frame of video data to a file. This file is in the windows bitmap format.

Parameter Description lpFileName Pointer to string containing filename with complete path.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_ERR_NOTINITIALISED The SDK has not been initialised to a

point where this function can be called. AVC_ERR_COLFMT_UNSUPPORTED

This function is only supported in RGB15 and RGB16 modes, calling this function with the colour format set to YUY2 will fail.

AVC_ERR_MEMORY The function failed whilst trying to allocate memory for the required buffers.

AVC_ERR_FILE_FAILURE The function failed whilst trying to write the bitmap to the specified filename.

Comments




A

AVC_GetCaptureRate

int AVC_GetCaptureRate (*bCapRate)

BYTE *bCapRate; /* Capture rate */

The AVC_GetCaptureRate function is used to get the capture rate currently being used by the capture engine. Parameter Description *bCapRate Pointer to variable to hold the current setting for the capture

rate. This value can have only two values, AVC_FULL_FRAME_RATE (1), or AVC_HALF_FRAME_RATE(2).

Returns


Value Description



Comments

To apply changes made to the configuration by this software the AVC_Restart must be called.

See also

AVC_SetCaptureRate




A

AVC_SetCaptureRate

int AVC_SetCaptureRate (bCapRate)

BYTE bCapRate; /* Capture rate */

The AVC_SetCaptureRate function is used to control the frequency at which AVC2000 grabs video data.

Parameter Description bCapRate This value controls the video capture rate. Currently this can

have only two values, AVC_FULL_FRAME_RATE (1), or AVC_HALF_FRAME_RATE(2).

Returns


Value Description

AVC_SUCCESS The function completed successfully.


Comments


See also

AVC_GetCaptureRate




A

AVC_InvertCapture

int AVC_InvertCapture (bInvertCapture)

BOOL bInvertCapture; /* Invert video */

The AVC_InvertCapture function is used to control whether the hardware inverts the captured video about the y-axis during the capture process.

Parameter Description bInvertCapture It can be useful in certain cases to invert the video data. If

this value is TRUE then the video is inverted if FALSE the video remains as normal.

Returns


Value Description

AVC_SUCCESS ` The function completed successfully. AVC_ERR_NOTINITIALISED The SDK has not been initialised to a point


Comments




A

Input Viewport functions

AVC_SetInputViewport

int AVC_SetInputViewport (uWidth, uHeight, uXoffset, uYoffset)

USHORT uWidth; /* capture width */

USHORT uHeight; /* capture height */

USHORT uXoffset; /* capture x-offset */

USHORT uYoffset; /* capture y-offset */

The AVC_SetInputViewport function sets the Input viewport for the capture process. The values passed to this function cannot exceed the maximum values for the relevant video format.

Parameter Description uWidth Width of the capture. uHeight Height of the capture. uXoffset X offset of capture from origin (top-left corner) of video

source. This value is currently not used and should be set to NULL.

uYoffset Y offset of capture from origin of video source. This value is currently not used and should be set to NULL.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_ERR_PARAM There was a parameter error. One of the

values exceeded the sizes supported by the driver for the current active video standard


Comments

To apply changes made to the configuration by this software the AVC_Restart (page 18) must be called.

See also

AVC_SetInputFormat




A

AVC_SetInputSource

int AVC_SetInputSource (bInput)

BYTE bInput; /* Desired input source */

The AVC_SetInputSource function is used to set the video source that is used by the AVC2000. This source can be one of two composite inputs or an S-video input.

Parameter Description bInput Desired Input Source Value Description INPUT_COMPOSITE1

(0x03) Selects the first composite input. This is the default input source that the driver uses.

INPUT_COMPOSITE2 (0x00)

Selects the second composite input.

INPUT_S_VIDEO (0x01)

Selects the S-Video input source.

There is an additional input (INPUT_RESERVED) that is reserved for future use, this value should not be used.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed. AVC_ERR_NOTINITIALISED The SDK has not been initialised to a

point where this function can be called.

Comments

This function is only required to change the video source away from the default first composite source. If only one composite source is used there is no need to call this function.

See also

AVC_GetInputSource




A

AVC_GetInputSource

int AVC_GetInputSource (*bInput)

BYTE *bInput; /* Input source */

The AVC_GetInputSource function is used to retrieve the ID of the currently active video input source.

Parameter Description *bInput Pointer to hold value of currently used Input Source. The

explanation of this values is as follows. Value Description INPUT_COMPOSITE1

(0x03) The first composite input is selected. This is the default input source that the driver uses.

INPUT_COMPOSITE2 (0x00)

The second composite input is selected.

INPUT_S_VIDEO (0x01) The S-Video input source is selected. There is an additional input (INPUT_RESERVED) that is

reserved for future use, this value should not be used.

Returns


Value Description



Comments

See also

AVC_SetInputSource




A

Configuration Functions

AVC_GetBrightness

int AVC_GetBrightness (*bBrightness)

BYTE *bBrightness; /* */

The AVC_GetBrightness function is used to get the current brightness setting of the capture process. Parameter Description *bBrightness

Pointer to variable to hold the current used brightness value

Returns


Value Description



Comments

See also

AVC_SetBrightness




A

AVC_SetBrightness

int AVC_SetBrightness (bBrightness)

BYTE bBrightness; /* Brightness control setting */

The AVC_SetBrightness function is used to control the brightness of the captured data. This value is set during the initialisation to the default value of 0x10. Parameter Description bBrightness Brightness control setting. This allows the brightness to be

adjusted between –50% and +49.6% of the input signal brightness. This value is in 2’s complement form with 0x7F representing the maximum increase of 49.6% and 0x80 the maximum reduction of 50%.

Returns


Value Description



Comments

See also

AVC_GetBrightness




A

AVC_GetContrast

int AVC_GetContrast (*wContrast)

WORD *wContrast; /* */

The AVC_GetContrast function is used to get the current contrast setting of the capture process. Parameter Description *wContrast Pointer to variable to hold the current contrast setting

Returns


Value Description



Comments

See also

AVC_SetContrast




A

AVC_SetContrast

int AVC_SetContrast (wContrast)

WORD wContrast; /* contrast control setting */

The AVC_SetContrast function is provided to allow for contrast adjustment of the captured data.

Parameter Description wContrast Contrast control setting. This value allows the contrast to be

varied between 0% and 236.57% of the input signal. The contrast is set to 0% by writing 0x0000 and the maximum value, 236.57%, is set by 0x1FF. The default value is set by writing 0x00D8; this sets the contrast to 100% of the original signal.

Returns


Value Description



Comments

See also

AVC_GetContrast




A

AVC_GetHue

int AVC_GetHue (*bHue)

BYTE *bHue; /* */

The AVC_GetHue function is used to get the current hue setting of the capture process. Parameter Description *bHue Pointer to variable to hold the current hue setting.

Returns


Value Description



Comments

See also

AVC_SetHue




A

AVC_SetHue

int AVC_SetHue (bHue)

BYTE bHue; /* hue control setting */

The AVC_SetHue function is used to control the Hue of the captured data.

Parameter Description bHue Hue control setting. This allows the hue to be adjusted between

–90 and +89.3 in 256 steps. The value used is a 2’s

complement number where a –90 change is produced by 0x80

and a +89.3 change by 0x7F. The default value of 0x00 does not adjust the hue of the capture.

Returns


Value Description



Comments

See also

AVC_GetHue




A

AVC_GetSaturation

int AVC_GetSaturation (*wSatU, *wSatV)

WORD *wSatU; /* */

WORD *wSatV; /* */

The AVC_GetSaturation function is used to get the current saturation settings of the capture process. Parameter Description *wSatU Pointer to variable to hold the current saturation value for the U

component. *wSatV Pointer to variable to hold the current saturation value for the V

component.

Returns


Value Description



Comments

See Also

AVC_SetSaturation




A

AVC_SetSaturation

int AVC_SetSaturation (wSatU, wSatV)

WORD wSatU; /* saturation setting for U component */

WORD wSatV; /* saturation setting for Y component */

The AVC_SetSaturation function is used to adjust the saturation of the input source. Parameter Description wSatU U components saturation control setting. This value is used to

range the saturation between 0 and 201.18% of the input signal. The minimum (0%) is set by 0x0000 and the maximum (201.18%) by 0x01FF. The default value is 0x00FE and this provides 100% of the original signal

wSatV V components saturation control setting. This value is used to range the saturation between 0 and 283.89% of the input signal. The minimum (0%) is set by 0x0000 and the maximum (283.89%) by 0x01FF. The default value is 0x00B4 and this provides 100% of the original signal

Returns


Value Description



Comments

See also

AVC_GetSaturation




A

AVC_GetInputFormat

int AVC_GetInputFormat (*uFormat)

USHORT *uFormat; /* pointer to video format */

The AVC_GetInputFormat function is used to return the current Video Input format that the driver is using.

Parameter Description *uFormat Pointer to variable to hold the current input format. This value

can be of either FORMAT_NTSC for the NTSC standard or FORMAT_PAL for the PAL standard.

Returns


Value Description



Comments

See also

AVC_SetInputFormat




A

AVC_SetInputFormat

int AVC_SetInputFormat (uFormat)

USHORT uFormat; /* Input video format */

The AVC_SetInputFormat function is used to set the Input Video format to the desired type, i.e. either NTSC or PAL.

Parameter Description uFormat This value can be of either FORMAT_NTSC (1) to set the Input

Video type to the NTSC standard or FORMAT_PAL (0) to set the Input Video type to the PAL standard.

Returns


Value Description



Comments


See also

AVC_GetInputFormat




A

AVC_GetColorFormat

int AVC_GetColorFormat (*uColFormat)

USHORT *uColFormat; /* */

The AVC_GetColorFormat function returns the colour format that is currently being used for captured video data.

Parameter Description *uColFormat Pointer to variable to hold the value of the currently used

colour format setting. This value can be one of the following Value Meaning YUY2 (0x00) YUY2 RGB15 (0x01) RGB555 RGB16 (0x02) RGB565

Returns


Value Description



Comments

See also

AVC_SetColorFormat




A

AVC_SetColorFormat int AVC_SetColorFormat (uColFormat)

USHORT uColFormat; /* Colour format */

The AVC_SetColorFormat function is used to set the colour format of the output video data.

Parameter Description uColFormat This value can be one of the following Value Meaning YUY2 (0x00) YUY2 RGB15 (0x01) RGB555 RGB16 (0x02) RGB565

Returns


Value Description



Comments


See also

AVC_GetColorFormat




A

AVC_SetInputVideoMode

int AVC_SetInputVideoMode (uVideoMode)

USHORT uVideoMode; /* input video mode */

The AVC_SetInputVideoMode function sets the input video mode.

Parameter Description uVideoMode Specifies the required input video mode. This parameter can be

one of the following values Value Meaning INPUT_INTERLACE

(0x00) Video is interlaced. Input viewports with the height over 240 lines will be de-interlaced using a software bob. This is the default value.

INPUT_NONINTERLACE (0x01)

Video is non-interlaced.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_ERR_PARAM The parameters supplied to the function are

invalid

Comments

The software bob for de-interlace captures each field individually and scales it up to the required overlay window size. This causes a small reduction in quality but overcomes motion artefacts caused by interlaced video being shown on a progressive monitor. This function must be called before AVC_SetInputViewport.

See also

AVC_SetInputViewport AVC_GetInputVideoMode




A

AVC_GetInputVideoMode

USHORT AVC_GetInputVideoMode (void)

The AVC_GetInputVideoMode function determines the current input video mode.

Returns

The return value is a USHORT that gives the input video mode. The value can be one of the following values:

Value Description

INPUT_INTERLACE (0x00) Interlace mode INPUT_NONINTERLACE (0x01) Non-interlace mode

Comments

This function returns the setting previous set using AVC_SetInputVideoMode . It will not tell you the whether the input video is interlaced or not.

See also

AVC_SetInputVideoMode.




A

Direct X Functions

AVC_OutputFullscreen

int AVC_OutputFullscreen (void)

The AVC_OutputFullscreen function is used to display the captured video fullscreen using DirectX

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed.

Call AVC_GetLastError() for extended error information.


Comments

This function is only available in DirectX mode, i.e. after AVC_InitDX has been called.

See also

AVC_InitDX AVC_GetLastError




A

AVC_OutputWindowed int AVC_OutputWindowed (left, top, width, height)

int left; /* video window x-offset from top left corner */

int top; /* video window y-offset from top left corner */

int width; /* video window width */

int height; /* video window height */

The AVC_OutputWindowed function is used to display the captured video to the specified region.

Parameter Description uVideoMode Specifies the required input video mode. This parameter can be

one of the following values left Video window x-offset from top left-hand corner of display. top Video window y-offset from top left-hand corner of display. width Width of the video window. height Height of the video window.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_ERR_PARAM The parameters supplied to the function are

invalid. The parameters must not produce a situation where any section of the overlay window would be positioned offscreen.

AVC_FAILURE An error occurred and the function failed. Call AVC_GetLastError() for extended error information.


Comments

This function is only available in DirectX mode, i.e. after AVC_InitDX has been called. The dimension settings here are independent of the input capture size. This function uses the display hardware to resize the captured video to the required size before displaying the data.

See also

AVC_InitDX AVC_GetLastError




A

AVC_HideVideo

int AVC_HideVideo (bHideVideo)

BOOL bHideVideo; /* Hide video */

The AVC_HideVideo function is used to toggle the visibility of the video window.

Parameter Description bHideVideo Boolean value to control whether the video window is hidden

or visible. If TRUE the video window is hidden if FALSE the video window is visible.

Returns


Value Description



Comments

This function is only available in DirectX mode, i.e. after AVC_InitDX has been called.

See also

AVC_InitDX




A

Color Key Functions

AVC_GetColorKey

int AVC_GetColorKey (*LowValue, *HighValue)

int *LowValue; /* pointer to low value variable */

int *HighValue; /* pointer to high value variable */

The AVC_GetColorKey function is used to get the color key information currently being used by the overlay surface.

Parameter Description *LowValue Pointer to hold returned low value. *HighValue Pointer to hold returned high value.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed. AVC_NO_COLOR_KEY_AVAIL The overlay surface does not support

colour keying.

Comments

See also

AVC_SetColorKey




A

AVC_SetColorKey

int AVC_SetColorKey (LowValue, HighValue)

int LowValue; /* color key low value */

int HighValue; /* color key high value */

The AVC_SetColorKey function is used to set the color key details used by the overlay surface. Parameter Description LowValue Low value, inclusive, of the colour range that is to be used as

the colour key. HighValue High value, inclusive, of the colour range that is to be used as

the colour key.

Returns


Value Description

AVC_SUCCESS The function completed successfully. AVC_FAILURE An error occurred and the function failed. AVC_NO_COLOR_KEY_AVAIL The overlay surface does not support

colour keying.

Comments

The use of this function depends heavily on the display driver.

See also

AVC_GetColorKey




A

AVC_EnableAVCInterrupt

int AVC_EnableAVCInterrupt (bEnable)

BOOL bEnable; /* enable AVC interrupt */

The AVC_EnableAVCInterrupt function is used to control whether the AVC generates an interrupt when it receives new video data. This interrupt is enabled by default and must always be enabled when video capture is required. Disabling this interrupt will prevent the callback function register via AVC_RegisterCallback from being called when new video data is available. This can be useful to provide a pause like function to the capture process. Parameter Description bEnable TRUE enables the AVC interrupt, FALSE disables.

Returns


Value Description



Comments




A

Miscellaneous Functions

AVC_GetLastError

int AVC_GetLastError (void)

The AVC_GetLastError function

Returns

The return value is one of the ERRORCODES

Comments




A

AVC_DumpDriverVersion

int AVC_DumpDriverVersion (void)

The AVC_DumpDriverVersion function is used to force the AVC driver to dump it‟s version information to the debug terminal.

Returns


Value Description



Comments




A

AVC_SetIsrThreadPriority

BOOL AVC_SetIsrThreadPriority (nIsrThreadPriority)

int nIsrThreadPriority; /* ISR Thread priority */

The AVC_SetIsrThreadPriority function sets the priority of the ISR thread.

Parameter Description nIsrThreadPriority

Specifies the priority to set the ISR thread too. This value can be in the range 0-255 where 0 is highest priority.

Returns

The return value is TRUE if successful. Otherwise, it is FALSE.

Comments

The default value for the ISR thread priority is 0. If used, this function must be called before AVC_EnableCapture




A

Error Codes

The table below lists all of the error codes returned by the various functions of the SDK.

Name Value Description

AVC_SUCCESS 0x0000

AVC_FAILURE 0x00E0

AVC_INVALID_PARAM 0x00E2

AVC_CANNOT_FULLSCREEN 0xE010

AVC_OVERLAY_CANNOT_STRETCH 0xE011

AVC_OVERLAY_SHRINK_ERROR 0xE012

AVC_OVERLAY_STRETCH_ERROR 0xE013

AVC_NO_COLOR_KEY_AVAIL 0xE014

AVC_ERR_NO_WINDOW 0xE020

AVC_ERR_DDRAW_CANNOT_CREATE 0xE021

AVC_ERR_DDRAW_QUERY_INTERFACE 0xE022

AVC_ERR_DDRAW_SETCOOPLEVEL 0xE023

AVC_ERR_DDRAW_CREATE_PRIMARY 0xE024

AVC_ERR_DDRAW_GETCAPS 0xE025

AVC_ERR_DDRAW_NOOVERLAY 0xE026

AVC_ERR_DDRAW_UNSUPPORTED_OVERLAY 0xE027

AVC_ERR_COLFMT_UNSUPPORTED 0xE030

AVC_ERR_FILE_FAILURE 0xE040

AVC_ERR_NOTINITIALISED 0xE050

AVC_ERR_MODE 0xE051

AVC_ERR_PARAM 0xE052

AVC_ERR_MEMORY 0xE0A0

AVC_ERR_LOADING_DRIVER 0xE0A1




A

Glossary

The table below lists the important defines that are contained within the SDK header files.

Name Value Description

RGB16 2 RGB15 1 YUY2 0 AVC_HUE_MIN 0x80 -90 degrees AVC_HUE_MAX 0x7F +89.3 degrees AVC_HUE_NOM 0x00 0 degrees AVC_SAT_MIN 0x0000 0.00% of original signal AVC_SAT_MAX 0x01FF 236.57% of original signal AVC_SAT_NOM 0x00D8 100% of original signal AVC_CONTR_MIN 0x0000 0.00% of original signal AVC_CONTR_MAX 0x01FF 236.57% of original signal AVC_CONTR_NOM 0x00D8 100% of original signal AVC_BRIGHT_MIN 0x80 -128 AVC_BRIGHT_MAX 0x7F +127 AVC_BRIGHT_NOM 0x00 0 AVC_MODE_CAPTURE 0 AVC_MODE_SINGLE 1 AVC_FULL_FRAME_RATE 1 Process every video frame AVC_HALF_FRAME_RATE 2 Process only every other frame FORMAT_NTSC 1 FORMAT_PAL 0 INPUT_COMPOSITE1 0x03 First composite video source INPUT_COMPOSITE2 0x00 Second composite video source INPUT_S_VIDEO 0x01 S-Video video source. INPUT_RESERVED 0x02 Input video source reserved for

future use.

6: Function Index AVC2000 Windows CE Overlay SDK Software Reference Manual



A

6:

Function Index

A

AVC_CloseSDK ................................................ 14 AVC_CustomInit ............................................... 17 AVC_DumpDriverVersion ................................. 54 AVC_EnableAVCInterrupt ................................ 52 AVC_EnableCapture ........................................ 24 AVC_GetBrightness.......................................... 33 AVC_GetCaptureRate ...................................... 27 AVC_GetColorFormat....................................... 43 AVC_GetColorKey ............................................ 50 AVC_GetContrast ............................................. 35 AVC_GetHue .................................................... 37 AVC_GetInputFormat ....................................... 41 AVC_GetInputSource ....................................... 32 AVC_GetInputVideoMode ................................ 46 AVC_GetLastError ............................................ 53 AVC_GetSaturation .......................................... 39 AVC_GetValidBuffer ......................................... 23 AVC_GrabFrame .............................................. 25 AVC_HideVideo ................................................ 49 AVC_InitDX ....................................................... 15

AVC_InitSDK .................................................. 12 AVC_InvertCapture .......................................... 29 AVC_OutputFullscreen .................................... 47 AVC_OutputWindowed .................................... 48 AVC_RegisterCallback .................................... 20 AVC_RegisterOverlayCallback ........................ 21 AVC_Restart .................................................... 18 AVC_SaveFrame ............................................. 26 AVC_SetBrightness ......................................... 34 AVC_SetCaptureRate ...................................... 28 AVC_SetColorFormat ...................................... 44 AVC_SetColorKey ........................................... 51 AVC_SetContrast............................................. 36 AVC_SetHue .................................................... 38 AVC_SetInputFormat ....................................... 42 AVC_SetInputSource ....................................... 31 AVC_SetInputVideoMode ................................ 45 AVC_SetInputViewport .................................... 30 AVC_SetIsrThreadPriority ............................... 55 AVC_SetPhysicalBuffers ................................. 22 AVC_SetSaturation .......................................... 40



A:

Contacting AMP

Sales

AMP‟s sales team is always available to assist you in choosing the board that best meets your requirements. Contact your local sales office or hotline.

Sales office US Sales office UK

Advanced Micro Peripherals Inc. Suite 424, 234 5th Ave New York NY, 10001 USA Tel: +1 212 951 7205 Fax: +1 212 951 7206 E-mail: [email protected] Web: www.amp-usa.com

Advanced Micro Peripherals Ltd. 1 Harrier House, Sedgeway Business Park Witchford, Cambridge, CB6 2HY United Kingdom Tel: +44 (0)1353 659500 Fax: 01353 659600 E-mail: [email protected] Web: www.ampltd.com

Technical support

Comprehensive technical information is available on our websites (see above).

If you can‟t find the information or solution you require, AMP has a team of technical support engineers / embedded video experts available to provide a quick and free response to your technical queries.

Please submit your technical support query to the appropriate email address:

Technical support US Technical support UK

E-mail: [email protected] E-mail: [email protected]

mailto:[email protected]

http://www.amp-usa.com/


http://www.ampltd.com/


software reference manual - prosoft.rud0%a0%d1�%d0%ba%d0%be%d… · required to develop overlay...

Documents