Display

The display functions provide an easy and fast way to display images. More...

Data Structures

struct	IC4_DISPLAY_STATS A structure containing display statistics. More...
struct	IC4_DISPLAY Represents a display that can be used to display images. More...

Macros

#define

IC4_WINDOW_HANDLE_NULL platform_specific

An invalid window handle value.

Typedefs

typedef platform_specific	IC4_WINDOW_HANDLE A window handle to be used as parent.
typedef void(*	ic4_display_window_closed_handler) (struct IC4_DISPLAY pDisplay, void user_ptr) Function pointer for the window-closed handler.
typedef void(*	ic4_display_window_closed_deleter) (void *user_ptr) Function pointer for cleanup of the device-lost user data.

Enumerations

enum	IC4_DISPLAY_TYPE { IC4_DISPLAY_DEFAULT , IC4_DISPLAY_WIN32_OPENGL } Defines the possible display types. More...
enum	IC4_DISPLAY_RENDER_POSITION { IC4_DISPLAY_RENDER_POSITION_TOPLEFT , IC4_DISPLAY_RENDER_POSITION_CENTER , IC4_DISPLAY_RENDER_POSITION_STRETCH_TOPLEFT , IC4_DISPLAY_RENDER_POSITION_STRETCH_CENTER , IC4_DISPLAY_RENDER_POSITION_CUSTOM } Contains the possible display alignment and stretch modes. More...

Functions

bool	ic4_display_create (enum IC4_DISPLAY_TYPE type, IC4_WINDOW_HANDLE parent, struct IC4_DISPLAY **ppDisplay) Creates a new display.
bool	ic4_display_create_external_opengl (struct IC4_DISPLAY **ppDisplay) Creates a new external OpenGL display.
struct IC4_DISPLAY *	ic4_display_ref (struct IC4_DISPLAY *pDisplay) Increases the display's internal reference count by one.
void	ic4_display_unref (struct IC4_DISPLAY *pDisplay) Decreases the display's internal reference count by one.
bool	ic4_display_display_buffer (struct IC4_DISPLAY pDisplay, const struct IC4_IMAGE_BUFFER buffer) Displays a specific image buffer.
bool	ic4_display_get_stats (struct IC4_DISPLAY pDisplay, struct IC4_DISPLAY_STATS stats) Queries statistics about a display.
bool	ic4_display_set_render_position (struct IC4_DISPLAY *pDisplay, enum IC4_DISPLAY_RENDER_POSITION pos, int left, int top, int width, int height) Configure the image scaling and alignment options for a display.
bool	ic4_display_event_add_window_closed (struct IC4_DISPLAY pDisplay, ic4_display_window_closed_handler handler, void user_ptr, ic4_display_window_closed_deleter deleter) Registers a callback to be called when the display is closed.
bool	ic4_display_event_remove_window_closed (struct IC4_DISPLAY pDisplay, ic4_display_window_closed_handler handler, void user_ptr) Unregisters a display-closed handler that was previously registered using ic4_display_event_add_window_closed().
bool	ic4_display_external_opengl_initialize (struct IC4_DISPLAY *pDisplay) Initialize the external OpenGL display.
bool	ic4_display_external_opengl_render (struct IC4_DISPLAY *pDisplay, int width, int height) Updates the external OpenGL display with the latest image available.
bool	ic4_display_external_opengl_notify_window_closed (struct IC4_DISPLAY *pDisplay) Notifies the external OpenGL display component that the window has been closed.

Detailed Description

The display functions provide an easy and fast way to display images.

To create a display, call ic4_display_create().

Macro Definition Documentation

◆ IC4_WINDOW_HANDLE_NULL

#define IC4_WINDOW_HANDLE_NULL platform_specific

An invalid window handle value.

When passed to a function, this value specifies that no parent window is set.

The value of IC4_WINDOW_HANDLE_NULL is platform-specific.

Typedef Documentation

◆ ic4_display_window_closed_deleter

typedef void(* ic4_display_window_closed_deleter) (void *user_ptr)

Function pointer for cleanup of the device-lost user data.

Parameters

[in] user_ptr User data that was specified when calling ic4_grabber_event_add_device_lost()

◆ ic4_display_window_closed_handler

typedef void(* ic4_display_window_closed_handler) (struct IC4_DISPLAY *pDisplay, void *user_ptr)

Function pointer for the window-closed handler.

Parameters

[in]	pDisplay	Pointer to the display whose window was closed
[in]	user_ptr	User data that was specified when calling ic4_display_event_add_window_closed()

◆ IC4_WINDOW_HANDLE

typedef platform_specific IC4_WINDOW_HANDLE

A window handle to be used as parent.

The type of IC4_WINDOW_HANDLE is platform-specific.

Enumeration Type Documentation

◆ IC4_DISPLAY_RENDER_POSITION

enum IC4_DISPLAY_RENDER_POSITION

Contains the possible display alignment and stretch modes.

Enumerator
IC4_DISPLAY_RENDER_POSITION_TOPLEFT	Display images unscaled at the top left corner of the window.
IC4_DISPLAY_RENDER_POSITION_CENTER	Display images unscaled an the center of the window.
IC4_DISPLAY_RENDER_POSITION_STRETCH_TOPLEFT	Display images stretched at the top left corner of the window.
IC4_DISPLAY_RENDER_POSITION_STRETCH_CENTER	Display images stretched at the center of the window.
IC4_DISPLAY_RENDER_POSITION_CUSTOM	Display images at custom coordinates.

◆ IC4_DISPLAY_TYPE

enum IC4_DISPLAY_TYPE

Defines the possible display types.

Enumerator

Enumerator
IC4_DISPLAY_DEFAULT	Selects the platform's default display type. For Windows, this is IC4_DISPLAY_WIN32_OPENGL.
IC4_DISPLAY_WIN32_OPENGL	Optimized OpenGL display for Windows platform.

IC4_DISPLAY_DEFAULT

Selects the platform's default display type.

For Windows, this is IC4_DISPLAY_WIN32_OPENGL.

IC4_DISPLAY_WIN32_OPENGL

Optimized OpenGL display for Windows platform.

Function Documentation

◆ ic4_display_create()

bool ic4_display_create	(	enum IC4_DISPLAY_TYPE	type,
		IC4_WINDOW_HANDLE	parent,
		struct IC4_DISPLAY **	ppDisplay
	)

Creates a new display.

Parameters

[in]	type	The type of display to create
[in]	parent	Handle to the parent window to embed the display into.
[out]	ppDisplay	Pointer to receive the handle to the new display object. When the display is no longer required, release the object reference using ic4_display_unref().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Warning: This function only works in Windows platforms. For other platforms, use ic4_display_create_external_opengl().

See also: ic4_display_unref

◆ ic4_display_create_external_opengl()

bool ic4_display_create_external_opengl ( struct IC4_DISPLAY ** ppDisplay )

Creates a new external OpenGL display.

Parameters

[out] ppDisplay Pointer to receive the handle to the new display object.
When the display is no longer required, release the object reference using ic4_display_unref().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks

To use the external renderer, the application has to follow these steps:

Create an OpenGL window, typically using the UI toolkit of the application
Call ic4_display_external_opengl_initialize with the OpenGL context activated for the active thread
Repeatedly call ic4_display_external_opengl_render with the OpenGL context activated for the active thread

See also: ic4_display_unref

◆ ic4_display_display_buffer()

bool ic4_display_display_buffer	(	struct IC4_DISPLAY *	pDisplay,
		const struct IC4_IMAGE_BUFFER *	buffer
	)

Displays a specific image buffer.

Parameters

[in]	pDisplay	A display
[in]	buffer	The buffer to display

Remarks: It is not always necessary to call this function.
When a display is registered with a IC4_GRABBER using ic4_grabber_set_display(), images are displayed automatically.

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks: When buffer is NULL, the display is cleared and will no longer display the previous buffer.

◆ ic4_display_event_add_window_closed()

bool ic4_display_event_add_window_closed	(	struct IC4_DISPLAY *	pDisplay,
		ic4_display_window_closed_handler	handler,
		void *	user_ptr,
		ic4_display_window_closed_deleter	deleter
	)

Registers a callback to be called when the display is closed.

Parameters

[in]	pDisplay	A display
[in]	handler	The function to be called when the display is closed
[in]	user_ptr	User data to be passed in calls to handler.
[in]	deleter	A function to be called when the handler was unregistered and the user_ptr will no longer be required. The deleter function can be used to release data associated with user_ptr. The deleter function will be called when the display-closed handler is unregistered, or the display object itself is destroyed.

Note: To unregister a display-closed handler, call ic4_display_event_remove_window_closed().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_display_event_remove_window_closed()

bool ic4_display_event_remove_window_closed	(	struct IC4_DISPLAY *	pDisplay,
		ic4_display_window_closed_handler	handler,
		void *	user_ptr
	)

Unregisters a display-closed handler that was previously registered using ic4_display_event_add_window_closed().

Parameters

[in]	pDisplay	The display on which the callback is currently registered
[in]	handler	Pointer to the function to be unregistered
[in]	user_ptr	User data that the function was previously registered with

Note: The pair of handler and user_ptr has to be an exact match to the parameters used in the call to ic4_display_event_add_window_closed().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_display_external_opengl_initialize()

bool ic4_display_external_opengl_initialize ( struct IC4_DISPLAY * pDisplay )

Initialize the external OpenGL display.

Parameters

[in] pDisplay The external OpenGL display

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks: This function must be called with the OpenGL context activated for the executing thread (e.g. makeCurrent).

◆ ic4_display_external_opengl_notify_window_closed()

bool ic4_display_external_opengl_notify_window_closed ( struct IC4_DISPLAY * pDisplay )

Notifies the external OpenGL display component that the window has been closed.

Parameters

[in] pDisplay The external OpenGL display

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_display_external_opengl_render()

bool ic4_display_external_opengl_render	(	struct IC4_DISPLAY *	pDisplay,
		int	width,
		int	height
	)

Updates the external OpenGL display with the latest image available.

Parameters

[in]	pDisplay	The external OpenGL display
[in]	width	Width of the display window in physical pixels
[in]	height	Height of the display window in physical pixels

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Remarks: This function must be called with the OpenGL context activated for the executing thread (e.g. makeCurrent).

◆ ic4_display_get_stats()

bool ic4_display_get_stats	(	struct IC4_DISPLAY *	pDisplay,
		struct IC4_DISPLAY_STATS *	stats
	)

Queries statistics about a display.

Parameters

[in]	pDisplay	A display
[out]	stats	Pointer to a IC4_DISPLAY_STATS structure receiving statistics about the display

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_display_ref()

struct IC4_DISPLAY * ic4_display_ref ( struct IC4_DISPLAY * pDisplay )

Increases the display's internal reference count by one.

Parameters

[in] pDisplay A pointer to a display

Returns: The pointer passed via pDisplay

Remarks: If pDisplay is NULL, the function returns NULL. An error value is not set.

See also: ic4_display_unref

◆ ic4_display_set_render_position()

bool ic4_display_set_render_position	(	struct IC4_DISPLAY *	pDisplay,
		enum IC4_DISPLAY_RENDER_POSITION	pos,
		int	left,
		int	top,
		int	width,
		int	height
	)

Configure the image scaling and alignment options for a display.

Parameters

[in]	pDisplay	A display
[in]	pos	The scaling and alignment mode to use
[in]	left	The left coordinate of the target rectangle inside the display window
[in]	top	The top coordinate of the target rectangle inside the display window
[in]	width	The width of the target rectangle inside the display window
[in]	height	The height of the target rectangle inside the display window

Remarks: The left, top, width and height parameters are ignored unless pos is IC4_DISPLAY_RENDER_POSITION_CUSTOM.

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_display_unref()

void ic4_display_unref ( struct IC4_DISPLAY * pDisplay )

Decreases the display's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters

[in] pDisplay A pointer to a display

Remarks: If pDisplay is NULL, the function does nothing. An error value is not set.

See also: ic4_display_ref