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_can_render (struct IC4_DISPLAY pDisplay, const struct IC4_IMAGE_TYPE image_type)
	Checks whether the display can render images of a specified image type.

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() or ic4_display_create_external_opengl().

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

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_can_render()

bool ic4_display_can_render	(	struct IC4_DISPLAY *	pDisplay,
		const struct IC4_IMAGE_TYPE *	image_type
	)

Checks whether the display can render images of a specified image type.

Parameters

[in]	pDisplay	A pointer to a display
[in]	image_type	The image type to check

Returns: true if the display can render the specified image type, otherwise false.
If an error occurs, the function returns false. Use ic4_get_last_error() to query error information.

◆ 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.; A zoom effect can be created by setting width and height to a multiple of the width and height of the image buffer(s) to be displayed. Set left and top to negative values to specifiy the top left corner of the visible image.

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

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IC4_WINDOW_HANDLE_NULL

Typedef Documentation

◆ ic4_display_window_closed_deleter

◆ ic4_display_window_closed_handler

◆ IC4_WINDOW_HANDLE

Enumeration Type Documentation

◆ IC4_DISPLAY_RENDER_POSITION

◆ IC4_DISPLAY_TYPE

Function Documentation

◆ ic4_display_can_render()

◆ ic4_display_create()

◆ ic4_display_create_external_opengl()

◆ ic4_display_display_buffer()

◆ ic4_display_event_add_window_closed()

◆ ic4_display_event_remove_window_closed()

◆ ic4_display_external_opengl_initialize()

◆ ic4_display_external_opengl_notify_window_closed()

◆ ic4_display_external_opengl_render()

◆ ic4_display_get_stats()

◆ ic4_display_ref()

◆ ic4_display_set_render_position()

◆ ic4_display_unref()