## Please enable JavaScript to view this site.

# FALCON/EAGLE user manual 4.62

- Zoom window out
- Larger text | Smaller text
- Hide page header
- Show expanding text
- Print topic
- Send mail feedback
- Copy topic URL

is_DirectRenderer | Scroll Previous Top Next More

Syntax

INT is_DirectRenderer (HIDS hCam, UINT nMode, void* pParam, UINT nSize)

Description

is_DirectRenderer() provides a set of advanced rendering functions and allows inserting overlay data into the camera's live image without flicker. The graphics card functions of the Direct3D library are supported under Windows.

•A current version of Microsoft’s DirectX9 runtime environment has to be installed on the system in order to be able to use Direct3D functions. For installation packages search the Microsoft website for "DirectX end user runtime".

•The graphics card must support a texture size (i.e. overlay size) of at least 768 x 576 pixels for PAL and 649 x 480 pixels for NTSC, respectively. You can read out the maximum texture size using the DR_GET_MAX_OVERLAY_SIZE parameter.

•To enable the Direct3D display call
is_SetDisplayMode(h, IS_SET_DM_DIRECT3D)

•Several different color modes can be used for image display in Direct3D mode. However, the highest performance is achieved when the FALCON color mode is identical to the Windows desktop color mode. In connection with modern, powerful graphics cards the grab format can usually be set to YUV 4:2:2. This format provides 16 bits per pixel and thus reduces the PCI/PCIe bus load compared to the RGB32 format, for example.

•Internal Direct3D may sometimes become invalid after re-activating the desktop in certain situations (such as: disabling a screen saver after keyboard input, having pressed the Ctrl-Alt-Del key combination). When this happens, the overlay data is lost. The application gets signaled via the Overlay-Lost message by the FALCON driver and can redraw the overlay data (see code example below). The message is sent both to the display window and the parent window of the display window. Thus, the message can be received even when the display control itself can not process messages. However, the message has to be processed by only one of the two window handlers.

•Direct3D provides an option for stepless display scaling (see DR_ENABLE_SCALING). Please note that downscaling interlaced image data may lead to less satisfying display quality compared to images which are already captured with the desired resolution.

•Some of the FALCON SDK functions can not be used in Direct3D mode (see list below).

Parameters

hf | Frame grabber handle
nMode | Direct3D function mode
DR_GET_OVERLAY_DC | Returns the device context (DC) handle to the overlay area of the graphics card.
| More informationen
In Direct3D mode, the DR_GET_OVERLAY_DC mode returns the device context (DC) handle of the overlay area. Using this handle, it is possible to access the overlay using the Windows GDI functionality. Thus, all Windows graphics commands (e.g. Line, Circle, Rectangle, TextOut) are available. To transfer the drawn elements to the overlay, release the DC handle by calling DR_RELEASE_OVERLAY_DC.
DR_RELEASE_OVERLAY_DC | Releases the device context (DC) handle.
| More informationen
Using DR_RELEASE_OVERLAY_DC, you can release the DC handle and update the overlay data
DR_GET_MAX_OVERLAY_SIZE | Reurns the width x and height y of the maximum overlay area supported by the graphics card.
DR_SET_OVERLAY_SIZE | Defines the size of the overlay area (default: current camera image size).
DR_SET_OVERLAY_POSITION | Defines the position of the overlay area.
DR_GET_OVERLAY_KEY_COLOR | Returns the RGB values of the current key color (default: black).
DR_SET_OVERLAY_KEY_COLOR | Defines the RGB values of the key color.
| More informationen
The key color specifies where the camera image will be visible in the overlay area. For example: if you fill the complete overlay with the key color, the whole camera image will be visible. If you fill part of the overlay with a different color, the camera image will be covered by the overlay in those places. The key color has no effect in semi-transparent mode!
DR_SHOW_OVERLAY | Enables overlay display on top of the current camera image
DR_HIDE_OVERLAY | Disables overlay display.
DR_ENABLE_SCALING | Enables real-time scaling of the image to the size of the display window.
DR_DISABLE_SCALING | Disables real-time scaling.
DR_ENABLE_SEMI_TRANSPARENT _OVERLAY | Enables a semi-transparent display of the overlay area.
| More informationen
In semi-transparent mode, the values of the camera image and the overlay data are added up for each pixel. Since black has the value 0, the complete camera image will be visible if the overlay is black; if the overlay is white, only the overlay will be visible. With all other colors, the camera image will be visible with the overlay superimposed. The key color has no effect in semi-transparent mode!
DR_DISABLE_SEMI_TRANSPARENT _OVERLAY | Disables the semi-transparent display of the overlay area.
DR_SET_VSYNC_AUTO | Enables synchronization of the image display with the monitor's image rendering. The image is displayed upon the monitor's next VSYNC signal.
DR_SET_VSYNC_OFF | Disables image display synchronization. The image is displayed immediately.
DR_SET_USER_SYNC | Enables synchronization of the image display with a monitor pixel row specified by the user.
| More informationen
Note that the auto-VSYNC function might not always optimally synchronize image rendering. In this case, you can eliminate flicker by manually setting a suitable position for synchronization. The position needs to be determined individually, based on the camera type and the graphics card.
DR_GET_USER_SYNC_POSITION _RANGE | Returns the minimum and maximum row position for DR_SET_USER_SYNC.
DR_LOAD_OVERLAY_FROM_FILE | Loads a bitmap image (*.BMP file) into the overlay area. If the bitmap image is larger than the overlay area, the bitmap image is clipped.
DR_CLEAR_OVERLAY | Deletes the data of the overlay area by filling it with black color.
DR_STEAL_NEXT_FRAME | Copies the next image to the active user memory which was set with is_SetImageMem() (Steal function).
| More informationen
Using the pParam parameter, you specify when the function should return: •IS_WAIT: The function waits until the image save is complete. •IS_DONT_WAIT: The function returns immediately.
DR_SET_STEAL_FORMAT | Defines the color format identical to is_Prepare StealVideo().
| More informationen
For a list of all available color formats, see the function description for is_SetColorMode(). The default is IS_CM_RGB32. A value of 0xFFFFFFFF (-1) deactivates the steal mode (same as is_StealVideo(h, IS_EXIT_STEAL_VIDEO)).
DR_GET_STEAL_FORMAT | Returns the color format setting for the Steal function.
DR_SET_HWND | Sets a new window handle for image output in Direct3D. This requires the Direct3D interface to be re-initialized internally. All overlay data will be discarded and has to be redrawn by the application. The Overlay-Lost message signals to the application in this case (see also description above).
DR_CHECK_COMPATIBILITY | Returns whether the graphics card supports the Direct3D functions.
DR_CHECK_COLOR_MODE_SUPPORT | Checks whether the specified color modes can be used for display. The FALCON color mode has to be passed as source mode and the desired VGA mode as target mode.
| More informationen
Note: Not every graphics card supports all possible combinations of source modes and target modes. Which modes can actually be used depends on the graphics card’s hardware properties as well as the current Windows desktop color mode. The current Windows desktop color mode can be read out using the is_GetColorDepth() function. Some modes may increase CPU load. This is often the case for conversions from YUV 4:2:2 to RGB16 or RGB32.
pParam | Void-type pointer to a data object or an array of objects (depending on the mode selected using nMode).
nSize | Size (in bytes) of the data object in array

Return value

When used with DR_CHECK_COMPATIBILITY | IS_DR_DEVICE_CAPS_INSUFFICIENT The graphics hardware does not fully support the required Direct3D functions
When used with DR_CHECK_COLOR_MODE_SUPPORT | IS_DR_DEVICE_CAPS_INSUFFICIENT The graphics hardware is not able to perform the desired color space conversion in hardware.
IS_SUCCESS | General success message
IS_NO_SUCCESS | General error message
IS_DR_LIBRARY_NOT_FOUND | The DirectRender library could not be found
IS_DR_DEVICE_OUT_OF_MEMORY | Insufficient graphics adapter video memory
IS_DR_CANNOT_CREATE_SURFACE | The image or overlay surface could not be created
IS_DR_CANNOT_CREATE_VERTEX_BUFFER | The vertex buffer could not be created
IS_DR_CANNOT_CREATE_TEXTURE | The texture could not be created
IS_DR_CANNOT_LOCK_OVERLAY_SURFACE | The overlay surface could not be locked
IS_DR_CANNOT_UNLOCK_OVERLAY_SURFACE | The overlay surface could not be unlocked
IS_DR_CANNOT_GET_OVERLAY_DC | Cannot get the overlay surface DC
IS_DR_CANNOT_RELEASE_OVERLAY_DC | Cannot release the overlay surface DC
IS_DR_DEVICE_CAPS_INSUFFICIENT | Insufficient graphics adapter capabilities
IS_DR_SURFACE_LOST | Created surfaces were lost and recreated
IS_DR_CANNOT_LOCK_IMAGE_SURFACE | The image surface could not be locked
IS_DR_CANNOT_UNLOCK_IMAGE_SURFACE | The image surface could not be unlocked

The following functions can not be used together with the Direct3D mode

•is_SetVideoMode()

•is_SetColorMode()

•is_SetImageSize()

•is_UpdateDisplay()

•is_EnableDDOverlay()

•is_DisableDDOverlay()

•is_ScaleDDOverlay()

•is_ShowDDOverlay()

•is_HideDDOverlay()

•is_OvlSurfaceOffWhileMove()

•is_GetDC()

•is_ReleaseDC

•is_SetDDUpdateTime

•is_LockDDOverlayMem

•is_UnlockDDOverlayMem

•is_LockDDMem

•is_UnlockDDMem

•is_GetDDOvlSurface

•is_SetKeyColor

•is_SetKeyOffset

•is_AddToSequence

Examples

//------------------------------------

// DC-Handle

//------------------------------------

// Get DC handle for Overlay

HDC hDC;

is_DirectRenderer (h, DR_GET_OVERLAY_DC, (void*)&hDC, sizeof (hDC));

// Release DC handle

is_DirectRenderer (h, DR_RELEASE_OVERLAY_DC, NULL, NULL);

//------------------------------------

// Size of overlay

//------------------------------------

//Query maximum size of overlay area

UINT OverlaySize[2];

is_DirectRenderer (h, DR_GET_MAX_OVERLAY_SIZE,

(void*)OverlaySize, sizeof(OverlaySize));

INT nWidth = OverlaySize[0];

INT nHeight = OverlaySize[1];

//Set size of overlay area

UINT Size[2];

Size[0] = 100;

Size[1] = 120;

is_DirectRenderer (h, DR_SET_OVERLAY_SIZE, (void*)Size, sizeof (Size));

//Set position of overlay area

UINT Position[2];

Position[0] = 20;

Position[1] = 0;

is_DirectRenderer (h, DR_SET_OVERLAY_POSITION,

(void*)Position, sizeof (Position));

//------------------------------------

// Key color

//------------------------------------

// Get current key color

UINT OverlayKeyColor[3];

is_DirectRenderer (h, DR_GET_OVERLAY_KEY_COLOR,

(void*)OverlayKeyColor, sizeof(OverlayKeyColor));

INT nRed = OverlayKeyColor[0];

INT nGreen = OverlayKeyColor[1];

INT nBlue = OverlayKeyColor[2];

// Set new key color

OverlayKeyColor[0] = GetRValue(m_rgbKeyColor);

OverlayKeyColor[1] = GetGValue(m_rgbKeyColor);

OverlayKeyColor[2] = GetBValue(m_rgbKeyColor);

is_DirectRenderer (h, DR_SET_OVERLAY_KEY_COLOR,

(void*)OverlayKeyColor, sizeof(OverlayKeyColor));

//------------------------------------

// Display

//------------------------------------

// Show overlay

is_DirectRenderer (h, DR_SHOW_OVERLAY, NULL, NULL);

// Hide overlay

is_DirectRenderer (h, DR_HIDE_OVERLAY, NULL, NULL);

//------------------------------------

// Scaling

//------------------------------------

//Enable scaling

is_DirectRenderer (h, DR_ENABLE_SCALING, NULL, NULL);

//Disable scaling

is_DirectRenderer (h, DR_DISABLE_SCALING, NULL, NULL);

//------------------------------------

// Transparenz

//------------------------------------

//Enable semi-transparent overlay

is_DirectRenderer (h, DR_ENABLE_SEMI_TRANSPARENT_OVERLAY, NULL, NULL);

//Disable semi-transparent overlay

is_DirectRenderer (h, DR_DISABLE_SEMI_TRANSPARENT_OVERLAY, NULL, NULL);

//------------------------------------

// Synchronization

//------------------------------------

//Enable auto-synchronization

is_DirectRenderer (h, DR_SET_VSYNC_AUTO, NULL, NULL);

//User defined synchronization: Query range and set position

UINT UserSync[2];

is_DirectRenderer (h, DR_GET_USER_SYNC_POSITION_RANGE,

(void*)UserSync, sizeof (UserSync));

INT Min = UserSync[0];

INT Max = UserSync[1];

INT SyncPosition = 400;

is_DirectRenderer (h, DR_SET_USER_SYNC,

(void*)&SyncPosition, sizeof (SyncPosition));

//Disable synchronization

is_DirectRenderer (h, DR_SET_VSYNC_OFF, NULL, NULL);

//------------------------------------

// BMP file

//------------------------------------

// Load overlay from BMP file

is_DirectRenderer (h, DR_LOAD_OVERLAY_FROM_FILE,

(void*)”c:\test.bmp”, NULL);

//------------------------------------

// Delete overlay

//------------------------------------

// Delete overlay area

is_DirectRenderer (h, DR_CLEAR_OVERLAY, NULL, NULL);

//------------------------------------

// Steal mode

//------------------------------------

// Get and set color mode for image to be copied

INT nColorMode;

is_DirectRenderer (h, DR_GET_STEAL_FORMAT,

(void*)&nColorMode, sizeof (nColorMode));

nColorMode = IS_CM_Y8;

is_DirectRenderer (h, DR_SET_STEAL_FORMAT,

(void*)&nColorMode, sizeof (nColorMode));

// Copy image with function returning immediately

INT nwait = IS_WAIT;

is_DirectRenderer(h, DR_STEAL_NEXT_FRAME,

(void*)&wait, sizeof (wait));

//------------------------------------

// Handle to window

//------------------------------------

// Set new window handle for image display

is_DirectRenderer (h, DR_SET_HWND, (void*)&hWnd, sizeof (hWnd));

//------------------------------------

// Compatibility

//------------------------------------

//Check graphics card compatibility

INT nRet = is_DirectRenderer (h, DR_CHECK_COMPATIBILITY, NULL, NULL);

if (nRet == IS_DR_DEVICE_CAPS_INSUFFICIENT )

//Graphics card does not support Direct3D

//------------------------------------

// Check color mode

//------------------------------------

INT nVgaMode;

// Read out current desktop color depth

INT nRet = is_GetColorDepth(h, NULL, &nVgaMode);

INT Modes[2];

Modes[0] = IS_SET_CM_RGB16; // FALCON source mode (example)

Modes[1] = nVgaMode; // Graphics card target mode

// Check source mode and target mode

nRet = is_DirectRenderer(h, DR_CHECK_COLOR_MODE_SUPPORT, Modes,

2 * sizeof(INT));

if (nRet == IS_DR_DEVICE_CAPS_INSUFFICIENT )

//Graphics card does not support the current color space conversion

//------------------------------------

// „Overlay Lost“ message

//------------------------------------

// Example for a message handler of an MFC application

// in XX_sample.h

afx_msg LRESULT OnFalconMessage(WPARAM wParam, LPARAM lParam);

// in XX_sample.cpp

BEGIN_MESSAGE_MAP(...)

...

ON_MESSAGE(IS_FALCON_MESSAGE, OnFalconMessage)

END_MESSAGE_MAP()

LRESULT CXX_class::OnFalconMessage(WPARAM wParam, LPARAM lParam)

{

switch(wParam)

{

case :

// redraw the overlay data here

...

break;

} // end switch(wParam)

return 0;

} // end LRESULT CXX_class::OnFalconMessage

© 2020 IDS Imaging Development Systems GmbH