is_DirectRenderer

USB 2.0

USB 3.0

GigE

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.

The second input parameter nMode specifies the effect of the is_DirectRenderer() call.

The value of the third parameter pParam depends on the mode selected with nMode: For example, when setting the overlay size (nMode = DR_SET_OVERLAY_SIZE), a pointer to an array of two values (x and y) is passed (see code samples). When you load a bitmap image (nMode = DR_LOAD_OVERLAY_FROM_FILE), pParam passes the path to the file (see code samples). The required parameters are illustrated in the sample codes at the end of this section.

Achtung

Note on system requirements

•To use the Direct3D functionality, the appropriate version of the Microsoft DirectX Runtime has to be installed in your PC.

•When you are using high-resolution cameras, the maximum texture size supported by the graphics card should be at least 4096 x 4096 pixels. You can check the maximum texture size by reading out the D3D_GET_MAX_OVERLAY_SIZE parameter.

•The Direct3D mode automatically uses the Windows Desktop color depth setting for the display.

Please also read the notes on graphics cards which are provided in the System requirements chapter.

Hinweis

Note on displaying monochrome or raw data formats

To display monchrome or Bayer raw data in Direct3D, please set the appropriate constants using the is_SetDisplayMode() function.

Input parameters

hCam

Camera handle

DR_GET_SUPPORTED

Returns either if Direct3D or OpenGL is supported by the graphics card.

•IS_SET_DM_DIRECT3D:
Tests if Direct3D is suppported.

•IS_SET_DM_OPENGL:
Tests if OpenGL is supported.

Example

DR_GET_OVERLAY_DC

Returns the device context (DC) handle to the overlay area of the graphics card.

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.

Example

DR_RELEASE_OVERLAY_DC

Releases the device context (DC) handle.

Using DR_RELEASE_OVERLAY_DC, you can release the DC handle and update the overlay data.

Example

DR_GET_MAX_OVERLAY_SIZE

Returns the width x and height y of the maximum overlay area supported by the graphics card. Example

DR_SET_OVERLAY_SIZE

Defines the size of the overlay area (default: current camera image size). Example

DR_GET_OVERLAY_SIZE

Returns the size of the overlay area. (Sample: see DR_SET_OVERLAY_SIZE)

DR_SET_OVERLAY_POSITION

Defines the position of the overlay area. Example

DR_GET_OVERLAY_KEY_COLOR

Returns the RGB values of the current key color (default: black). Example

DR_SET_OVERLAY_KEY_COLOR

Defines the RGB values of the key color.

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!

Example

DR_SHOW_OVERLAY

Enables overlay display on top of the current camera image. Example

DR_HIDE_OVERLAY

Disables overlay display. Example

DR_ENABLE_SCALING

Enables real-time scaling of the image to the size of the display window. The overlay is scaled together with the camera image. Example

DR_ENABLE_IMAGE_SCALING

Enables real-time scaling of the image to the size of the display window. The overlay is not scaled. (Sample: see DR_ENABLE_SCALING)

DR_DISABLE_SCALING

Disables real-time scaling. Example

DR_ENABLE_SEMI_TRANSPARENT_OVERLAY

Enables a semi-transparent display of the overlay area.

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!

Example

DR_DISABLE_SEMI_TRANSPARENT_OVERLAY

Disables the semi-transparent display of the overlay area. Example

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. Example

DR_SET_VSYNC_OFF

Disables image display synchronization. The image is displayed immediately. Example

DR_SET_USER_SYNC

Enables synchronization of the image display with a monitor pixel row specified by the user.

When displaying very large camera images, 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.

Example

DR_GET_USER_SYNC_POSITION_RANGE

Returns the minimum and maximum row position for DR_SET_USER_SYNC. Example

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. Example

DR_CLEAR_OVERLAY

Deletes the data of the overlay area by filling it with black color. Example

DR_STEAL_NEXT_FRAME

Copies the next image to the active user memory (Steal function).

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.

Example

DR_SET_STEAL_FORMAT

Defines the color format for the Steal function.

For a list of all available color formats, see the function description for is_SetColorMode(). The default is IS_CM_BGRA8_PACKED (RGB 32).

Example

DR_GET_STEAL_FORMAT

Returns the color format setting for the Steal function. Example

DR_SET_HWND

Sets a new window handle for image output in Direct3D. Example

DR_CHECK_COMPATIBILITY

Returns whether the graphics card supports the uEye Direct3D functions. Example

pParam

Pointer to a data object or an array of objects (depending on the mode selected using nMode). The pointer pParam is of the type void.

nSize

Size (in bytes) of the data object or array.

Return values

When used with DR_CHECK_COMPATIBILITY	IS_DR_DEVICE_CAPS_INSUFFICIENT The graphics hardware does not fully support the uEye Direct3D functions.
IS_DR_CANNOT_CREATE_SURFACE	The image surface or overlay surface could not be created.
IS_DR_CANNOT_CREATE_TEXTURE	The texture could not be created.
IS_DR_CANNOT_CREATE_VERTEX_BUFFER	The vertex buffer could not be created.
IS_DR_CANNOT_GET_OVERLAY_DC	Could not get the device context handle for the overlay.
IS_DR_CANNOT_LOCK_OVERLAY_SURFACE	The overlay surface could not be locked.
IS_DR_CANNOT_RELEASE_OVERLAY_DC	Could not release the device context handle for the overlay.
IS_DR_CANNOT_UNLOCK_OVERLAY_SURFACE	The overlay surface could not be unlocked.
IS_DR_DEVICE_CAPS_INSUFFICIENT	Function is not supported by the graphics hardware.
IS_DR_DEVICE_OUT_OF_MEMORY	Not enough graphics memory available.
IS_DR_NOT_ALLOWED_WHILE_DC_IS_ACTIVE	A device context handle is still open in the application.
IS_INVALID_CAMERA_HANDLE	Invalid camera handle
IS_INVALID_PARAMETER	One of the submitted parameters is outside the valid range or is not supported for this sensor or is not available in this mode.
IS_NO_SUCCESS	General error message
IS_NOT_SUPPORTED	The camera model used here does not support this function or setting.
IS_SUCCESS	Function executed successfully
IS_TIMED_OUT	A timeout occurred. An image capturing process could not be terminated within the allowable period.

Related functions

Example Supported function

UINT nType = IS_SET_DM_DIRECT3D;

if (is_DirectRenderer(m_pMainView->GetCameraHandle(), DR_GET_SUPPORTED,

(void*)&nType, sizeof(nType)) == IS_SUCCESS)

{

// Direct3D is supported

}

nType = IS_SET_DM_OPENGL;

if (is_DirectRenderer(m_pMainView->GetCameraHandle(), DR_GET_SUPPORTED,

(void*)&nType, sizeof(nType)) == IS_SUCCESS)

{

// OpenGL is supported

}

Example DC handle

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

// DC-Handle

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

// Get DC handle for Overlay

HDC hDC;

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

// Release DC handle

is_DirectRenderer (hCam, DR_RELEASE_OVERLAY_DC, NULL, NULL);

Example overlay size and position

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

// Size of overlay

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

// Query maximum size of overlay area

UINT OverlaySize[2];

is_DirectRenderer (hCam, 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 (hCam, DR_SET_OVERLAY_SIZE,

(void*)Size, sizeof (Size));

// Set position of overlay area

UINT Position[2];

Position[0] = 20;

Position[1] = 0;

is_DirectRenderer (hCam, DR_SET_OVERLAY_POSITION,

void*)Position, sizeof (Position));

Example key color

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

// Key color

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

// Get current key color

UINT OverlayKeyColor[3];

is_DirectRenderer (hCam, 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 (hCam, DR_SET_OVERLAY_KEY_COLOR,

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

Example display

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

// Display

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

// Show overlay

is_DirectRenderer (hCam, DR_SHOW_OVERLAY, NULL, NULL);

// Hide overlay

is_DirectRenderer (hCam, DR_HIDE_OVERLAY, NULL, NULL);

Example scaling

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

// Scaling

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

// Enable scaling

is_DirectRenderer (hCam, DR_ENABLE_SCALING, NULL, NULL);

// Disable scaling

is_DirectRenderer (hCam, DR_DISABLE_SCALING, NULL, NULL);

Example transparency

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

// Transparency

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

// Enable semi-transparent overlay

is_DirectRenderer (hCam, DR_ENABLE_SEMI_TRANSPARENT_OVERLAY, NULL, NULL);

// Disable semi-transparent overlay

is_DirectRenderer (hCam, DR_DISABLE_SEMI_TRANSPARENT_OVERLAY, NULL, NULL);

Example synchronization

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

// Synchronization

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

// Enable auto-synchronization

is_DirectRenderer (hCam, DR_SET_VSYNC_AUTO, NULL, NULL);

// User defined synchronization: Query range and set position

UINT UserSync[2];

is_DirectRenderer (hCam, DR_GET_USER_SYNC_POSITION_RANGE,

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

INT Min = UserSync[0];

INT Max = UserSync[1];

INT SyncPosition = 400;

is_DirectRenderer (hCam, DR_SET_USER_SYNC,

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

// Disable synchronization

is_DirectRenderer (hCam, DR_SET_VSYNC_OFF, NULL, NULL);

Example overlay with BMP

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

// BMP file

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

// Load overlay from BMP file

is_DirectRenderer (hCam, DR_LOAD_OVERLAY_FROM_FILE,

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

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

// Delete overlay

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

// Delete overlay area

is_DirectRenderer (hCam, DR_CLEAR_OVERLAY, NULL, NULL);

Example steal mode

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

// Steal mode

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

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

INT nColorMode;

is_DirectRenderer (hCam, DR_GET_STEAL_FORMAT,

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

nColorMode = IS_CM_MONO8;

is_DirectRenderer (hCam, DR_SET_STEAL_FORMAT,

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

// Copy image with function returning immediately

INT nwait = IS_DONT_WAIT;

is_DirectRenderer(hCam, DR_STEAL_NEXT_FRAME,

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

Example window handle

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

// Handle to window

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

// Set new window handle for image display

is_DirectRenderer (hCam, DR_SET_HWND,

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

Example compatibility

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

// Compatibility

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

// Check graphics card compatibility

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

if (nRet == IS_DR_DEVICE_CAPS_INSUFFICIENT )

// Graphics card does not support Direct3D

Sample programs

•uEyeDirectRenderer

•uEyeSteal

Suggestion for improvement? Send us your short Feedback on this chapter. Thank you very much!

For technical questions please contact you local distributor or use the support form on our website.

Home > C: Programming > Function descriptions >	History back Previous chapter Next chapter Print
is_DirectRenderer