Allow the creation of windows, display images on them and manage user events (keyboard, mouse and windows events). More...

Constructors / Destructor / Instance Management
	~CImgDisplay ()
	Destructor. More...

	CImgDisplay ()
	Construct an empty display. More...

	CImgDisplay (const unsigned int width, const unsigned int height, const char *const title=0, const unsigned int normalization=3, const bool is_fullscreen=false, const bool is_closed=false)
	Construct a display with specified dimensions. More...

template<typename T >
	CImgDisplay (const CImg< T > &img, const char *const title=0, const unsigned int normalization=3, const bool is_fullscreen=false, const bool is_closed=false)
	Construct a display from an image. More...

template<typename T >
	CImgDisplay (const CImgList< T > &list, const char *const title=0, const unsigned int normalization=3, const bool is_fullscreen=false, const bool is_closed=false)
	Construct a display from an image list. More...

	CImgDisplay (const CImgDisplay &disp)
	Construct a display as a copy of an existing one. More...

CImgDisplay &	assign ()
	Destructor - Empty constructor [in-place version]. More...

CImgDisplay &	assign (const unsigned int width, const unsigned int height, const char *const title=0, const unsigned int normalization=3, const bool is_fullscreen=false, const bool is_closed=false)
	Construct a display with specified dimensions [in-place version].

template<typename T >
CImgDisplay &	assign (const CImg< T > &img, const char *const title=0, const unsigned int normalization=3, const bool is_fullscreen=false, const bool is_closed=false)
	Construct a display from an image [in-place version].

template<typename T >
CImgDisplay &	assign (const CImgList< T > &list, const char *const title=0, const unsigned int normalization=3, const bool is_fullscreen=false, const bool is_closed=false)
	Construct a display from an image list [in-place version].

CImgDisplay &	assign (const CImgDisplay &disp)
	Construct a display as a copy of another one [in-place version].

template<typename T >
static void	screenshot (CImg< T > &img)
	Take a screenshot. More...

static CImgDisplay &	empty ()
	Return a reference to an empty display. More...

static const CImgDisplay &	const_empty ()
	Return a reference to an empty display [const version].

Overloaded Operators
template<typename t >
CImgDisplay &	operator= (const CImg< t > &img)
	Display image on associated window. More...

template<typename t >
CImgDisplay &	operator= (const CImgList< t > &list)
	Display list of images on associated window. More...

CImgDisplay &	operator= (const CImgDisplay &disp)
	Construct a display as a copy of another one [in-place version]. More...

	operator bool () const
	Return `false` if display is empty, `true` otherwise. More...

Instance Checking
bool	is_empty () const
	Return `true` if display is empty, `false` otherwise.

bool	is_closed () const
	Return `true` if display is closed (i.e. not visible on the screen), `false` otherwise. More...

bool	is_visible () const
	Return `true` if display is visible (i.e. not closed by the user), `false` otherwise.

bool	is_resized () const
	Return `true` if associated window has been resized on the screen, `false` otherwise.

bool	is_moved () const
	Return `true` if associated window has been moved on the screen, `false` otherwise.

bool	is_event () const
	Return `true` if any event has occurred on the associated window, `false` otherwise.

bool	is_fullscreen () const
	Return `true` if current display is in fullscreen mode, `false` otherwise.

bool	is_key () const
	Return `true` if any key is being pressed on the associated window, `false` otherwise. More...

bool	is_key (const unsigned int keycode) const
	Return `true` if key specified by given keycode is being pressed on the associated window, `false` otherwise. More...

bool &	is_key (const char *const keycode)
	Return `true` if key specified by given keycode is being pressed on the associated window, `false` otherwise. More...

bool	is_key_sequence (const unsigned int *const keycodes_sequence, const unsigned int length, const bool remove_sequence=false)
	Return `true` if specified key sequence has been typed on the associated window, `false` otherwise. More...

bool	is_keyESC () const
	Return `true` if the `ESC` key is being pressed on the associated window, `false` otherwise. More...

bool	is_keyF1 () const

bool	is_keyF2 () const

bool	is_keyF3 () const

bool	is_keyF4 () const

bool	is_keyF5 () const

bool	is_keyF6 () const

bool	is_keyF7 () const

bool	is_keyF8 () const

bool	is_keyF9 () const

bool	is_keyF10 () const

bool	is_keyF11 () const

bool	is_keyF12 () const

bool	is_keyPAUSE () const

bool	is_key1 () const

bool	is_key2 () const

bool	is_key3 () const

bool	is_key4 () const

bool	is_key5 () const

bool	is_key6 () const

bool	is_key7 () const

bool	is_key8 () const

bool	is_key9 () const

bool	is_key0 () const

bool	is_keyBACKSPACE () const

bool	is_keyINSERT () const

bool	is_keyHOME () const

bool	is_keyPAGEUP () const

bool	is_keyTAB () const

bool	is_keyQ () const

bool	is_keyW () const

bool	is_keyE () const

bool	is_keyR () const

bool	is_keyT () const

bool	is_keyY () const

bool	is_keyU () const

bool	is_keyI () const

bool	is_keyO () const

bool	is_keyP () const

bool	is_keyDELETE () const

bool	is_keyEND () const

bool	is_keyPAGEDOWN () const

bool	is_keyCAPSLOCK () const

bool	is_keyA () const

bool	is_keyS () const

bool	is_keyD () const

bool	is_keyF () const

bool	is_keyG () const

bool	is_keyH () const

bool	is_keyJ () const

bool	is_keyK () const

bool	is_keyL () const

bool	is_keyENTER () const

bool	is_keySHIFTLEFT () const

bool	is_keyZ () const

bool	is_keyX () const

bool	is_keyC () const

bool	is_keyV () const

bool	is_keyB () const

bool	is_keyN () const

bool	is_keyM () const

bool	is_keySHIFTRIGHT () const

bool	is_keyARROWUP () const

bool	is_keyCTRLLEFT () const

bool	is_keyAPPLEFT () const

bool	is_keyALT () const

bool	is_keySPACE () const

bool	is_keyALTGR () const

bool	is_keyAPPRIGHT () const

bool	is_keyMENU () const

bool	is_keyCTRLRIGHT () const

bool	is_keyARROWLEFT () const

bool	is_keyARROWDOWN () const

bool	is_keyARROWRIGHT () const

bool	is_keyPAD0 () const

bool	is_keyPAD1 () const

bool	is_keyPAD2 () const

bool	is_keyPAD3 () const

bool	is_keyPAD4 () const

bool	is_keyPAD5 () const

bool	is_keyPAD6 () const

bool	is_keyPAD7 () const

bool	is_keyPAD8 () const

bool	is_keyPAD9 () const

bool	is_keyPADADD () const

bool	is_keyPADSUB () const

bool	is_keyPADMUL () const

bool	is_keyPADDIV () const

Instance Characteristics
int	width () const
	Return display width. More...

int	height () const
	Return display height. More...

unsigned int	normalization () const
	Return normalization type of the display. More...

const char *	title () const
	Return title of the associated window as a C-string. More...

int	window_width () const
	Return width of the associated window. More...

int	window_height () const
	Return height of the associated window. More...

int	window_x () const
	Return X-coordinate of the associated window. More...

int	window_y () const
	Return Y-coordinate of the associated window. More...

int	mouse_x () const
	Return X-coordinate of the mouse pointer. More...

int	mouse_y () const
	Return Y-coordinate of the mouse pointer. More...

unsigned int	button () const
	Return current state of the mouse buttons. More...

int	wheel () const
	Return current state of the mouse wheel. More...

unsigned int &	key (const unsigned int pos=0) const
	Return one entry from the pressed keys history. More...

unsigned int &	released_key (const unsigned int pos=0) const
	Return one entry from the released keys history. More...

float	frames_per_second ()
	Return the current refresh rate, in frames per second. More...

CImgDisplay &	move_inside_screen ()

static int	screen_width ()
	Return width of the screen (current resolution along the X-axis).

static int	screen_height ()
	Return height of the screen (current resolution along the Y-axis).

static unsigned int	keycode (const char *const keycode)
	Return keycode corresponding to the specified string. More...

Window Manipulation
template<typename T >
CImgDisplay &	display (const CImg< T > &img)
	Display image on associated window. More...

template<typename T >
CImgDisplay &	display (const CImgList< T > &list, const char axis='x', const float align=0)
	Display list of images on associated window. More...

CImgDisplay &	show ()
	Show (closed) associated window on the screen. More...

CImgDisplay &	close ()
	Close (visible) associated window and make it disappear from the screen. More...

CImgDisplay &	move (const int pos_x, const int pos_y)
	Move associated window to a new location. More...

CImgDisplay &	resize (const bool force_redraw=true)
	Resize display to the size of the associated window. More...

CImgDisplay &	resize (const int width, const int height, const bool force_redraw=true)
	Resize display to the specified size. More...

template<typename T >
CImgDisplay &	resize (const CImg< T > &img, const bool force_redraw=true)
	Resize display to the size of an input image. More...

CImgDisplay &	resize (const CImgDisplay &disp, const bool force_redraw=true)
	Resize display to the size of another CImgDisplay instance. More...

CImgDisplay &	set_normalization (const unsigned int normalization)
	Set normalization type. More...

CImgDisplay &	set_title (const char *const format,...)
	Set title of the associated window. More...

CImgDisplay &	set_fullscreen (const bool is_fullscreen, const bool force_redraw=true)
	Enable or disable fullscreen mode. More...

CImgDisplay &	toggle_fullscreen (const bool force_redraw=true)
	Toggle fullscreen mode. More...

CImgDisplay &	show_mouse ()
	Show mouse pointer. More...

CImgDisplay &	hide_mouse ()
	Hide mouse pointer. More...

CImgDisplay &	set_mouse (const int pos_x, const int pos_y)
	Move mouse pointer to a specified location. More...

CImgDisplay &	set_button ()
	Simulate a mouse button release event. More...

CImgDisplay &	set_button (const unsigned int button, const bool is_pressed=true)
	Simulate a mouse button press or release event. More...

CImgDisplay &	set_wheel ()
	Flush all mouse wheel events. More...

CImgDisplay &	set_wheel (const int amplitude)
	Simulate a wheel event. More...

CImgDisplay &	set_key ()
	Flush all key events. More...

CImgDisplay &	set_key (const unsigned int keycode, const bool is_pressed=true)
	Simulate a keyboard press/release event. More...

CImgDisplay &	flush ()
	Flush all display events. More...

CImgDisplay &	wait ()
	Wait for any user event occurring on the current display.

CImgDisplay &	wait (const unsigned int milliseconds)
	Wait for a given number of milliseconds since the last call to wait(). More...

template<typename T >
CImgDisplay &	render (const CImg< T > &img)
	Render image into internal display buffer. More...

CImgDisplay &	paint ()
	Paint internal display buffer on associated window. More...

template<typename T >
const CImgDisplay &	snapshot (CImg< T > &img) const
	Take a snapshot of the associated window content. More...

static void	wait (CImgDisplay &disp1)
	Wait for any event occurring on the display `disp1`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2)
	Wait for any event occurring either on the display `disp1` or `disp2`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3)
	Wait for any event occurring either on the display `disp1`, `disp2` or `disp3`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3` or `disp4`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4, CImgDisplay &disp5)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3`, `disp4` or `disp5`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4, CImgDisplay &disp5, CImgDisplay &disp6)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3`, `disp4`, ... `disp6`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4, CImgDisplay &disp5, CImgDisplay &disp6, CImgDisplay &disp7)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3`, `disp4`, ... `disp7`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4, CImgDisplay &disp5, CImgDisplay &disp6, CImgDisplay &disp7, CImgDisplay &disp8)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3`, `disp4`, ... `disp8`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4, CImgDisplay &disp5, CImgDisplay &disp6, CImgDisplay &disp7, CImgDisplay &disp8, CImgDisplay &disp9)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3`, `disp4`, ... `disp9`.

static void	wait (CImgDisplay &disp1, CImgDisplay &disp2, CImgDisplay &disp3, CImgDisplay &disp4, CImgDisplay &disp5, CImgDisplay &disp6, CImgDisplay &disp7, CImgDisplay &disp8, CImgDisplay &disp9, CImgDisplay &disp10)
	Wait for any event occurring either on the display `disp1`, `disp2`, `disp3`, `disp4`, ... `disp10`.

static void	wait_all ()
	Wait for any window event occurring in any opened CImgDisplay.

template<typename T >
static void	screenshot (const int x0, const int y0, const int x1, const int y1, CImg< T > &img)
	Take a snapshot of the current screen content. More...

Detailed Description

Allow the creation of windows, display images on them and manage user events (keyboard, mouse and windows events).

CImgDisplay methods rely on a low-level graphic library to perform: it can be either X-Window (X11, for Unix-based systems) or GDI32 (for Windows-based systems). If both libraries are missing, CImgDisplay will not be able to display images on screen, and will enter a minimal mode where warning messages will be outputted each time the program is trying to call one of the CImgDisplay method.

The configuration variable cimg_display tells about the graphic library used. It is set automatically by CImg when one of these graphic libraries has been detected. But, you can override its value if necessary. Valid choices are:

0: Disable display capabilities.
1: Use X-Window (X11) library.
2: Use GDI32 library.

Remember to link your program against X11 or GDI32 libraries if you use CImgDisplay.

Constructor & Destructor Documentation

◆ ~CImgDisplay()

~CImgDisplay ( )

Destructor.

Note: If the associated window is visible on the screen, it is closed by the call to the destructor.

◆ CImgDisplay() [1/5]

CImgDisplay ( )

Construct an empty display.

Note: Constructing an empty CImgDisplay instance does not make a window appearing on the screen, until display of valid data is performed.

Example: CImgDisplay disp; // Does actually nothing

...

disp.display(img); // Construct new window and display image in it

cimg_library::CImgDisplay::CImgDisplay
CImgDisplay()
Construct an empty display.
Definition: CImg.h:8319

◆ CImgDisplay() [2/5]

CImgDisplay	(	const unsigned int	width,
		const unsigned int	height,
		const char *const	title = `0`,
		const unsigned int	normalization = `3`,
		const bool	is_fullscreen = `false`,
		const bool	is_closed = `false`
	)

Construct a display with specified dimensions.

Parameters

width	Window width.
height	Window height.
title	Window title.
normalization	Normalization type (`0`=none, `1`=always, `2`=once, `3`=pixel type-dependent, see normalization()).
is_fullscreen	Tells if fullscreen mode is enabled.
is_closed	Tells if associated window is initially visible or not.

Note: A black background is initially displayed on the associated window.

◆ CImgDisplay() [3/5]

CImgDisplay	(	const CImg< T > &	img,
		const char *const	title = `0`,
		const unsigned int	normalization = `3`,
		const bool	is_fullscreen = `false`,
		const bool	is_closed = `false`
	)

explicit

Construct a display from an image.

Parameters

img	Image used as a model to create the window.
title	Window title.
normalization	Normalization type (`0`=none, `1`=always, `2`=once, `3`=pixel type-dependent, see normalization()).
is_fullscreen	Tells if fullscreen mode is enabled.
is_closed	Tells if associated window is initially visible or not.

Note: The pixels of the input image are initially displayed on the associated window.

◆ CImgDisplay() [4/5]

CImgDisplay	(	const CImgList< T > &	list,
		const char *const	title = `0`,
		const unsigned int	normalization = `3`,
		const bool	is_fullscreen = `false`,
		const bool	is_closed = `false`
	)

explicit

Construct a display from an image list.

Parameters

list	The images list to display.
title	Window title.
normalization	Normalization type (`0`=none, `1`=always, `2`=once, `3`=pixel type-dependent, see normalization()).
is_fullscreen	Tells if fullscreen mode is enabled.
is_closed	Tells if associated window is initially visible or not.

Note: All images of the list, appended along the X-axis, are initially displayed on the associated window.

◆ CImgDisplay() [5/5]

CImgDisplay ( const CImgDisplay & disp )

Construct a display as a copy of an existing one.

Parameters

disp	Display instance to copy.

Note: The pixel buffer of the input window is initially displayed on the associated window.

Member Function Documentation

◆ screenshot() [1/2]

static void screenshot ( CImg< T > & img )

static

Take a screenshot.

Parameters

[out] img Output screenshot. Can be empty on input

◆ assign()

CImgDisplay& assign ( )

Destructor - Empty constructor [in-place version].

Note: Replace the current instance by an empty display.

◆ empty()

static CImgDisplay& empty ( )

static

Return a reference to an empty display.

Note: Can be useful for writing function prototypes where one of the argument (of type CImgDisplay&) must have a default value.

Example: void foo(CImgDisplay& disp=CImgDisplay::empty());

cimg_library::CImgDisplay::empty
static CImgDisplay & empty()
Return a reference to an empty display.
Definition: CImg.h:8500

◆ operator=() [1/3]

CImgDisplay& operator= ( const CImg< t > & img )

Display image on associated window.

Note: disp = img is equivalent to disp.display(img).

◆ operator=() [2/3]

CImgDisplay& operator= ( const CImgList< t > & list )

Display list of images on associated window.

Note: disp = list is equivalent to disp.display(list).

◆ operator=() [3/3]

CImgDisplay& operator= ( const CImgDisplay & disp )

Construct a display as a copy of another one [in-place version].

Note: Equivalent to assign(const CImgDisplay&).

◆ operator bool()

operator bool ( ) const

Return false if display is empty, true otherwise.

Note: if (disp) { ... } is equivalent to if (!disp.is_empty()) { ... }.

◆ is_closed()

bool is_closed ( ) const

Return true if display is closed (i.e. not visible on the screen), false otherwise.

Note

When a user physically closes the associated window, the display is set to closed.
A closed display is not destroyed. Its associated window can be show again on the screen using show().

◆ is_key() [1/3]

bool is_key ( ) const

Return true if any key is being pressed on the associated window, false otherwise.

Note: The methods below do the same only for specific keys.

◆ is_key() [2/3]

bool is_key ( const unsigned int keycode ) const

Return true if key specified by given keycode is being pressed on the associated window, false otherwise.

Parameters

keycode Keycode to test.

Note: Keycode constants are defined in the cimg namespace and are architecture-dependent. Use them to ensure your code stay portable (see cimg::keyESC).

Example: CImgDisplay disp(400,400);

while (!disp.is_closed()) {

if (disp.key(cimg::keyTAB)) { ... } // Equivalent to 'if (disp.is_keyTAB())'

disp.wait();

}

cimg_library::cimg::keyTAB
const unsigned int keyTAB
Keycode for the TAB key (architecture-dependent)
Definition: CImg.h:3572

◆ is_key() [3/3]

bool& is_key ( const char *const keycode )

Return true if key specified by given keycode is being pressed on the associated window, false otherwise.

Parameters

keycode C-string containing the keycode label of the key to test.

Note: Use it when the key you want to test can be dynamically set by the user.

Example: CImgDisplay disp(400,400);

const char *const keycode = "TAB";

while (!disp.is_closed()) {

if (disp.is_key(keycode)) { ... } // Equivalent to 'if (disp.is_keyTAB())'

disp.wait();

}

cimg_library::CImgDisplay::keycode
static unsigned int keycode(const char *const keycode)
Return keycode corresponding to the specified string.
Definition: CImg.h:9070

◆ is_key_sequence()

bool is_key_sequence	(	const unsigned int *const	keycodes_sequence,
		const unsigned int	length,
		const bool	remove_sequence = `false`
	)

Return true if specified key sequence has been typed on the associated window, false otherwise.

Parameters

keycodes_sequence	Buffer of keycodes to test.
length	Number of keys in the `keycodes_sequence` buffer.
remove_sequence	Tells if the key sequence must be removed from the key history, if found.

Note: Keycode constants are defined in the cimg namespace and are architecture-dependent. Use them to ensure your code stay portable (see cimg::keyESC).

Example: CImgDisplay disp(400,400);

const unsigned int key_seq[] = { cimg::keyCTRLLEFT, cimg::keyD };

while (!disp.is_closed()) {

if (disp.is_key_sequence(key_seq,2)) { ... } // Test for the 'CTRL+D' keyboard event

disp.wait();

}

cimg_library::cimg::keyD
const unsigned int keyD
Keycode for the D key (architecture-dependent)
Definition: CImg.h:3589

cimg_library::cimg::keyCTRLLEFT
const unsigned int keyCTRLLEFT
Keycode for the CTRLLEFT key (architecture-dependent)
Definition: CImg.h:3607

◆ is_keyESC()

bool is_keyESC ( ) const

Return true if the ESC key is being pressed on the associated window, false otherwise.

Note: Similar methods exist for all keys managed by CImg (see cimg::keyESC).

◆ width()

int width ( ) const

Return display width.

Note: The width of the display (i.e. the width of the pixel data buffer associated to the CImgDisplay instance) may be different from the actual width of the associated window.

◆ height()

int height ( ) const

Return display height.

Note: The height of the display (i.e. the height of the pixel data buffer associated to the CImgDisplay instance) may be different from the actual height of the associated window.

◆ normalization()

unsigned int normalization ( ) const

Return normalization type of the display.

The normalization type tells about how the values of an input image are normalized by the CImgDisplay to be correctly displayed. The range of values for pixels displayed on screen is [0,255]. If the range of values of the data to display is different, a normalization may be required for displaying the data in a correct way. The normalization type can be one of:

0: Value normalization is disabled. It is then assumed that all input data to be displayed by the CImgDisplay instance have values in range [0,255].
1: Value normalization is always performed (this is the default behavior). Before displaying an input image, its values will be (virtually) stretched in range [0,255], so that the contrast of the displayed pixels will be maximum. Use this mode for images whose minimum and maximum values are not prescribed to known values (e.g. float-valued images). Note that when normalized versions of images are computed for display purposes, the actual values of these images are not modified.
2: Value normalization is performed once (on the first image display), then the same normalization coefficients are kept for next displayed frames.
3: Value normalization depends on the pixel type of the data to display. For integer pixel types, the normalization is done regarding the minimum/maximum values of the type (no normalization occurs then for unsigned char). For float-valued pixel types, the normalization is done regarding the minimum/maximum value of the image data instead.

◆ title()

const char* title ( ) const

Return title of the associated window as a C-string.

Note: Window title may be not visible, depending on the used window manager or if the current display is in fullscreen mode.

◆ window_width()

int window_width ( ) const

Return width of the associated window.

Note: The width of the display (i.e. the width of the pixel data buffer associated to the CImgDisplay instance) may be different from the actual width of the associated window.

◆ window_height()

int window_height ( ) const

Return height of the associated window.

Note: The height of the display (i.e. the height of the pixel data buffer associated to the CImgDisplay instance) may be different from the actual height of the associated window.

◆ window_x()

int window_x ( ) const

Return X-coordinate of the associated window.

Note: The returned coordinate corresponds to the location of the upper-left corner of the associated window.

◆ window_y()

int window_y ( ) const

Return Y-coordinate of the associated window.

Note: The returned coordinate corresponds to the location of the upper-left corner of the associated window.

◆ mouse_x()

int mouse_x ( ) const

Return X-coordinate of the mouse pointer.

Note

If the mouse pointer is outside window area, -1 is returned.
Otherwise, the returned value is in the range [0,width()-1].

◆ mouse_y()

int mouse_y ( ) const

Return Y-coordinate of the mouse pointer.

Note

If the mouse pointer is outside window area, -1 is returned.
Otherwise, the returned value is in the range [0,height()-1].

◆ button()

unsigned int button ( ) const

Return current state of the mouse buttons.

Note

Three mouse buttons can be managed. If one button is pressed, its corresponding bit in the returned value is set:

bit 0 (value 0x1): State of the left mouse button.
bit 1 (value 0x2): State of the right mouse button.
bit 2 (value 0x4): State of the middle mouse button.

Several bits can be activated if more than one button are pressed at the same time.

Example: CImgDisplay disp(400,400);

while (!disp.is_closed()) {

if (disp.button()&1) { // Left button clicked

...

}

if (disp.button()&2) { // Right button clicked

...

}

if (disp.button()&4) { // Middle button clicked

...

}

disp.wait();

}

◆ wheel()

int wheel ( ) const

Return current state of the mouse wheel.

Note

The returned value can be positive or negative depending on whether the mouse wheel has been scrolled forward or backward.
Scrolling the wheel forward add 1 to the wheel value.
Scrolling the wheel backward subtract 1 to the wheel value.
The returned value cumulates the number of forward of backward scrolls since the creation of the display, or since the last reset of the wheel value (using set_wheel()). It is strongly recommended to quickly reset the wheel counter when an action has been performed regarding the current wheel value. Otherwise, the returned wheel value may be for instance 0 despite the fact that many scrolls have been done (as many in forward as in backward directions).

Example: CImgDisplay disp(400,400);

while (!disp.is_closed()) {

if (disp.wheel()) {

int counter = disp.wheel(); // Read the state of the mouse wheel

... // Do what you want with 'counter'

disp.set_wheel(); // Reset the wheel value to 0

}

disp.wait();

}

◆ key()

unsigned int& key ( const unsigned int pos = 0 ) const

Return one entry from the pressed keys history.

Parameters

pos	Index to read from the pressed keys history (index `0` corresponds to latest entry).

Returns: Keycode of a pressed key or 0 for a released key.

Note

Each CImgDisplay stores a history of the pressed keys in a buffer of size 128. When a new key is pressed, its keycode is stored in the pressed keys history. When a key is released, 0 is put instead. This means that up to the 64 last pressed keys may be read from the pressed keys history. When a new value is stored, the pressed keys history is shifted so that the latest entry is always stored at position 0.
Keycode constants are defined in the cimg namespace and are architecture-dependent. Use them to ensure your code stay portable (see cimg::keyESC).

◆ released_key()

unsigned int& released_key ( const unsigned int pos = 0 ) const

Return one entry from the released keys history.

Parameters

pos	Index to read from the released keys history (index `0` corresponds to latest entry).

Returns: Keycode of a released key or 0 for a pressed key.

Note

Each CImgDisplay stores a history of the released keys in a buffer of size 128. When a new key is released, its keycode is stored in the pressed keys history. When a key is pressed, 0 is put instead. This means that up to the 64 last released keys may be read from the released keys history. When a new value is stored, the released keys history is shifted so that the latest entry is always stored at position 0.
Keycode constants are defined in the cimg namespace and are architecture-dependent. Use them to ensure your code stay portable (see cimg::keyESC).

◆ keycode()

static unsigned int keycode ( const char *const keycode )

static

Return keycode corresponding to the specified string.

Note: Keycode constants are defined in the cimg namespace and are architecture-dependent. Use them to ensure your code stay portable (see cimg::keyESC).

Example: const unsigned int keyTAB = CImgDisplay::keycode("TAB"); // Return cimg::keyTAB

◆ frames_per_second()

float frames_per_second ( )

Return the current refresh rate, in frames per second.

Note: Returns a significant value when the current instance is used to display successive frames. It measures the delay between successive calls to frames_per_second().

◆ display() [1/2]

CImgDisplay& display ( const CImg< T > & img )

Display image on associated window.

Parameters

img	Input image to display.

Note: This method returns immediately.

◆ display() [2/2]

CImgDisplay& display	(	const CImgList< T > &	list,
		const char	axis = `'x'`,
		const float	align = `0`
	)

Display list of images on associated window.

Parameters

list	List of images to display.
axis	Axis used to append the images along, for the visualization (can be `x`, `y`, `z` or `c`).
align	Relative position of aligned images when displaying lists with images of different sizes (`0` for upper-left, `0.5` for centering and `1` for lower-right).

Note: This method returns immediately.

◆ show()

CImgDisplay& show ( )

Show (closed) associated window on the screen.

Note

Force the associated window of a display to be visible on the screen, even if it has been closed before.
Using show() on a visible display does nothing.

◆ close()

CImgDisplay& close ( )

Close (visible) associated window and make it disappear from the screen.

Note

A closed display only means the associated window is not visible anymore. This does not mean the display has been destroyed. Use show() to make the associated window reappear.
Using close() on a closed display does nothing.

◆ move()

CImgDisplay& move	(	const int	pos_x,
		const int	pos_y
	)

Move associated window to a new location.

Parameters

pos_x	X-coordinate of the new window location.
pos_y	Y-coordinate of the new window location.

Note: Depending on the window manager behavior, this method may not succeed (no exceptions are thrown nevertheless).

◆ resize() [1/4]

CImgDisplay& resize ( const bool force_redraw = true )

Resize display to the size of the associated window.

Parameters

force_redraw Tells if the previous window content must be updated and refreshed as well.

Note

Calling this method ensures that width() and window_width() become equal, as well as height() and window_height().
The associated window is also resized to specified dimensions.

◆ resize() [2/4]

CImgDisplay& resize	(	const int	width,
		const int	height,
		const bool	force_redraw = `true`
	)

Resize display to the specified size.

Parameters

width	Requested display width.
height	Requested display height.
force_redraw	Tells if the previous window content must be updated and refreshed as well.

Note: The associated window is also resized to specified dimensions.

◆ resize() [3/4]

CImgDisplay& resize	(	const CImg< T > &	img,
		const bool	force_redraw = `true`
	)

Resize display to the size of an input image.

Parameters

img	Input image to take size from.
force_redraw	Tells if the previous window content must be resized and updated as well.

Note

Calling this method ensures that width() and img.width() become equal, as well as height() and img.height().
The associated window is also resized to specified dimensions.

◆ resize() [4/4]

CImgDisplay& resize	(	const CImgDisplay &	disp,
		const bool	force_redraw = `true`
	)

Resize display to the size of another CImgDisplay instance.

Parameters

disp	Input display to take size from.
force_redraw	Tells if the previous window content must be resized and updated as well.

Note

Calling this method ensures that width() and disp.width() become equal, as well as height() and disp.height().
The associated window is also resized to specified dimensions.

◆ set_normalization()

CImgDisplay& set_normalization ( const unsigned int normalization )

Set normalization type.

Parameters

normalization New normalization mode.

◆ set_title()

CImgDisplay& set_title	(	const char *const	format,
			...
	)

Set title of the associated window.

Parameters

format C-string containing the format of the title, as with std::printf().

Warning: As the first argument is a format string, it is highly recommended to write
disp.set_title("%s",window_title);

instead of
disp.set_title(window_title);

if window_title can be arbitrary, to prevent nasty memory access.

◆ set_fullscreen()

CImgDisplay& set_fullscreen	(	const bool	is_fullscreen,
		const bool	force_redraw = `true`
	)

Enable or disable fullscreen mode.

Parameters

is_fullscreen	Tells is the fullscreen mode must be activated or not.
force_redraw	Tells if the previous window content must be displayed as well.

Note

When the fullscreen mode is enabled, the associated window fills the entire screen but the size of the current display is not modified.
The screen resolution may be switched to fit the associated window size and ensure it appears the largest as possible. For X-Window (X11) users, the configuration flag cimg_use_xrandr has to be set to allow the screen resolution change (requires the X11 extensions to be enabled).

◆ toggle_fullscreen()

CImgDisplay& toggle_fullscreen ( const bool force_redraw = true )

Toggle fullscreen mode.

Parameters

force_redraw Tells if the previous window content must be displayed as well.

Note: Enable fullscreen mode if it was not enabled, and disable it otherwise.

◆ show_mouse()

CImgDisplay& show_mouse ( )

Show mouse pointer.

Note: Depending on the window manager behavior, this method may not succeed (no exceptions are thrown nevertheless).

◆ hide_mouse()

CImgDisplay& hide_mouse ( )

Hide mouse pointer.

Note: Depending on the window manager behavior, this method may not succeed (no exceptions are thrown nevertheless).

◆ set_mouse()

CImgDisplay& set_mouse	(	const int	pos_x,
		const int	pos_y
	)

Move mouse pointer to a specified location.

Note: Depending on the window manager behavior, this method may not succeed (no exceptions are thrown nevertheless).

◆ set_button() [1/2]

CImgDisplay& set_button ( )

Simulate a mouse button release event.

Note: All mouse buttons are considered released at the same time.

◆ set_button() [2/2]

CImgDisplay& set_button	(	const unsigned int	button,
		const bool	is_pressed = `true`
	)

Simulate a mouse button press or release event.

Parameters

button	Buttons event code, where each button is associated to a single bit.
is_pressed	Tells if the mouse button is considered as pressed or released.

◆ set_wheel() [1/2]

CImgDisplay& set_wheel ( )

Flush all mouse wheel events.

Note: Make wheel() to return 0, if called afterwards.

◆ set_wheel() [2/2]

CImgDisplay& set_wheel ( const int amplitude )

Simulate a wheel event.

Parameters

amplitude Amplitude of the wheel scrolling to simulate.

Note: Make wheel() to return amplitude, if called afterwards.

◆ set_key() [1/2]

CImgDisplay& set_key ( )

Flush all key events.

Note: Make key() to return 0, if called afterwards.

◆ set_key() [2/2]

CImgDisplay& set_key	(	const unsigned int	keycode,
		const bool	is_pressed = `true`
	)

Simulate a keyboard press/release event.

Parameters

keycode	Keycode of the associated key.
is_pressed	Tells if the key is considered as pressed or released.

Note: Keycode constants are defined in the cimg namespace and are architecture-dependent. Use them to ensure your code stay portable (see cimg::keyESC).

◆ flush()

CImgDisplay& flush ( )

Flush all display events.

Note: Remove all passed events from the current display.

◆ wait()

CImgDisplay& wait ( const unsigned int milliseconds )

Wait for a given number of milliseconds since the last call to wait().

Parameters

milliseconds Number of milliseconds to wait for.

Note: Similar to cimg::wait().

◆ render()

CImgDisplay& render ( const CImg< T > & img )

Render image into internal display buffer.

Parameters

img	Input image data to render.

Note

Convert image data representation into the internal display buffer (architecture-dependent structure).
The content of the associated window is not modified, until paint() is called.
Should not be used for common CImgDisplay uses, since display() is more useful.

◆ paint()

CImgDisplay& paint ( )

Paint internal display buffer on associated window.

Note

Update the content of the associated window with the internal display buffer, e.g. after a render() call.
Should not be used for common CImgDisplay uses, since display() is more useful.

◆ screenshot() [2/2]

static void screenshot	(	const int	x0,
		const int	y0,
		const int	x1,
		const int	y1,
		CImg< T > &	img
	)

static

Take a snapshot of the current screen content.

Parameters

	x0	X-coordinate of the upper left corner.
	y0	Y-coordinate of the upper left corner.
	x1	X-coordinate of the lower right corner.
	y1	Y-coordinate of the lower right corner.
[out]	img	Output screenshot. Can be empty on input

◆ snapshot()

const CImgDisplay& snapshot ( CImg< T > & img ) const

Take a snapshot of the associated window content.

Parameters

[out] img Output snapshot. Can be empty on input.

Latest stable version: 3.4.3 Current pre-release: 3.5.0 (2024/12/23)

Constructors / Destructor / Instance Management

Overloaded Operators

Instance Checking

Instance Characteristics

Window Manipulation

Detailed Description

Constructor & Destructor Documentation

◆ ~CImgDisplay()

◆ CImgDisplay() [1/5]

◆ CImgDisplay() [2/5]

◆ CImgDisplay() [3/5]

◆ CImgDisplay() [4/5]

◆ CImgDisplay() [5/5]

Member Function Documentation

◆ screenshot() [1/2]

◆ assign()

◆ empty()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator bool()

◆ is_closed()

◆ is_key() [1/3]

◆ is_key() [2/3]

◆ is_key() [3/3]

◆ is_key_sequence()

◆ is_keyESC()

◆ width()

◆ height()

◆ normalization()

◆ title()

◆ window_width()

◆ window_height()

◆ window_x()

◆ window_y()

◆ mouse_x()

◆ mouse_y()

◆ button()

◆ wheel()

◆ key()

◆ released_key()

◆ keycode()

◆ frames_per_second()

◆ display() [1/2]

◆ display() [2/2]

◆ show()

◆ close()

◆ move()

◆ resize() [1/4]

◆ resize() [2/4]

◆ resize() [3/4]

◆ resize() [4/4]

◆ set_normalization()

◆ set_title()

◆ set_fullscreen()

◆ toggle_fullscreen()

◆ show_mouse()

◆ hide_mouse()

◆ set_mouse()

◆ set_button() [1/2]

◆ set_button() [2/2]

◆ set_wheel() [1/2]

◆ set_wheel() [2/2]

◆ set_key() [1/2]

◆ set_key() [2/2]

◆ flush()

◆ wait()

◆ render()

◆ paint()

◆ screenshot() [2/2]

◆ snapshot()