The C++ Template Image Processing Library. |

[Introduction]- [News]- [Download]- [Screenshots]- [Tutorial]- [Forums]- [Reference]- [SourceForge Repository ]

Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members

# CImgDisplay Struct Reference

This class is used to create a display window, draw images into it and handle mouse and keyboard events. More...

List of all members.

## Public Member Functions

const int | dimx () const
| Return the width of the display window, as a signed integer.
const int | dimy () const
| Return the height of the display window, as a signed integer.
const CImgDisplay & | wait (const unsigned int milliseconds) const
| Synchronized waiting function. Same as cimg::wait().
template<typename T>
CImgDisplay & | display (const CImgl< T > &list, const char axe='x', const char align='c')
| Display an image list CImgl<T> into a display window.
template<typename T>
CImgDisplay & | resize (const CImg< T > &img, const bool redraw=false, const bool force=true)
| Resize a display window with the size of an image.
| CImgDisplay (const unsigned int dimw, const unsigned int dimh, const char *title=NULL, const unsigned int normalization_type=1, const unsigned int events_type=3, const bool fullscreen_flag=false, const bool closed_flag=false)
| Create a display window with a specified size `pwidth` x `height`.
template<typename T>
| CImgDisplay (const CImg< T > &img, const char *title=NULL, const unsigned int normalization_type=1, const unsigned int events_type=3, const bool fullscreen_flag=false, const bool closed_flag=false)
| Create a display window from an image.
template<typename T>
| CImgDisplay (const CImgl< T > &list, const char *title=NULL, const unsigned int normalization_type=1, const unsigned int events_type=3, const bool fullscreen_flag=false, const bool closed_flag=false)
| Create a display window from an image list.
| CImgDisplay (const CImgDisplay &win, char *title=NULL)
| Create a display window by copying another one.
CImgDisplay & | resize (const int width, const int height, const bool redraw=false, const bool force=true)
| Resize a display window with new dimensions `width` and `height`.
CImgDisplay & | move (const int posx, const int posy)
| Move a display window at a specific location `posx`, `posy`.
const int | window_posx () const
| Return the X-coordinate of a window.
const int | window_posy () const
| Return the Y-coordinate of a window.
| ~CImgDisplay ()
| Destructor. Close and destroy a display.
template<typename T>
void | render (const CImg< T > &img, const unsigned int ymin=0, const unsigned int ymax=~0)
| Fill the pixel data of the window buffer according to the image `pimg`.
template<typename T>
CImgDisplay & | display (const CImg< T > &img, const unsigned int ymin=0, const unsigned int ymax=-1)
| Display an image in a window.
CImgDisplay & | wait ()
| Wait for a window event.
CImgDisplay & | show ()
| Show a closed display.
CImgDisplay & | close ()
| Close a visible display.

## Public Attributes

unsigned int | width
| Variable representing the width of the display.
unsigned int | height
| Variable representing the height of the display.
volatile unsigned int | window_width
| Variable representing the width of the window associated to the current display (should be considered as read-only).
volatile unsigned int | window_height
| Variable representing the height of the window associated to the current display (should be considered as read-only).
unsigned int | normalization
| Variable defining the pixel normalization behavior of the display window (can be modified on the fly).
unsigned int | events
| Variable representing the type of events handled by the display window (should be considered as read-only).
const bool | fullscreen
| Variable indicating if the display is fullscreen (should be considered as read-only).
volatile int | mousex
| Variable representing the current x-coordinate of the mouse pointer over the display window (should be considered as read-only).
volatile int | mousey
| Variable representing the current y-coordinate of the mouse pointer over the display window. (should be considered as read only).
volatile unsigned int | button
| Variable representing the state of the mouse buttons when the mouse pointer is over the display window. (should be considered as read only).
volatile unsigned int | key
| Variable representing the key pressed when mouse pointer is over the display window.
volatile bool | closed
| Variable representing the visibility state of the display window (should be read only).
volatile bool | resized
| Event-variable.

## Detailed Description

This class is used to create a display window, draw images into it and handle mouse and keyboard events.

Creating a `CImgDisplay` instance opens a window that can be used to display a `CImg<T>` image of a `CImgl<T>` image list inside. When a display is created, associated window events (such as mouse motion, keyboard and window size changes) are handled and can be easily detected by testing specific `CImgDisplay` data fields. See Using Display Windows. for a complete tutorial on using the `CImgDisplay` class.

Definition at line 1758 of file CImg.h.

## Constructor & Destructor Documentation

CImgDisplay | ( | const unsigned int | dimw,
|  | const unsigned int | dimh,
|  | const char * | title = `NULL`,
|  | const unsigned int | normalization_type = `1`,
|  | const unsigned int | events_type = `3`,
|  | const bool | fullscreen_flag = `false`,
|  | const bool | closed_flag = `false`
| ) |

Create a display window with a specified size `pwidth` x `height`.

Parameters:

  | dimw | : Width of the display window.
  | dimh | : Height of the display window.
  | title | : Title of the display window.
  | normalization_type | : Normalization type of the display window (see CImgDisplay::normalize).
  | events_type | : Type of events handled by the display window.
  | fullscreen_flag | : Fullscreen mode.
  | closed_flag | : Initially visible mode. A black image will be initially displayed in the display window.

Definition at line 2050 of file CImg.h.

CImgDisplay | ( | const CImg< T > & | img,
|  | const char * | title = `NULL`,
|  | const unsigned int | normalization_type = `1`,
|  | const unsigned int | events_type = `3`,
|  | const bool | fullscreen_flag = `false`,
|  | const bool | closed_flag = `false`
| ) |

Create a display window from an image.

Parameters:

  | img | : Image that will be used to create the display window.
  | title | : Title of the display window
  | normalization_type | : Normalization type of the display window.
  | events_type | : Type of events handled by the display window.
  | fullscreen_flag | : Fullscreen mode.
  | closed_flag | : Initially visible mode.

Definition at line 2065 of file CImg.h.

CImgDisplay | ( | const CImgl< T > & | list,
|  | const char * | title = `NULL`,
|  | const unsigned int | normalization_type = `1`,
|  | const unsigned int | events_type = `3`,
|  | const bool | fullscreen_flag = `false`,
|  | const bool | closed_flag = `false`
| ) |

Create a display window from an image list.

Parameters:

  | list | : The list of images to display.
  | title | : Title of the display window
  | normalization_type | : Normalization type of the display window.
  | events_type | : Type of events handled by the display window.
  | fullscreen_flag | : Fullscreen mode.
  | closed_flag | : Initially visible mode.

Definition at line 2080 of file CImg.h.

CImgDisplay | ( | const CImgDisplay & | win,
|  | char * | title = `NULL`
| ) |

Create a display window by copying another one.

Parameters:

  | win | : Display window to copy.
  | title | : Title of the new display window.

Definition at line 2090 of file CImg.h.

## Member Function Documentation

const int dimx | ( |  | ) | const

Return the width of the display window, as a signed integer.

Note:
  When working with resizing window, `dimx()` does not necessarily return the width of the resized window, but the width of the internal data structure that can be used to display image. Resizing a display window can be done with the function CImgDisplay::resize().

See also:
  CImgDisplay::width, CImgDisplay::dimy(), CImgDisplay::resize()

Definition at line 1969 of file CImg.h.

const int dimy | ( |  | ) | const

Return the height of the display window, as a signed integer.

Note:
  When working with resizing window, `dimy()` does not necessarily return the height of the resized window, but the height of the internal data structure that can be used to display image. Resizing a display window can be done with the function CImgDisplay::resize().

See also:
  CImgDisplay::height, CImgDisplay::dimx(), CImgDisplay::resize()

Definition at line 1978 of file CImg.h.

const CImgDisplay& wait | ( | const unsigned int | milliseconds | ) | const

Synchronized waiting function. Same as cimg::wait().

See also:
  cimg::wait()

Definition at line 1992 of file CImg.h.

CImgDisplay& display | ( | const CImgl< T > & | list,
|  | const char | axe = `'x'`,
|  | const char | align = `'c'`
| ) |

Display an image list CImgl<T> into a display window.

First, all images of the list are appended into a single image used for visualization, then this image is displayed in the current display window.

Parameters:

  | list | : The list of images to display.
  | axe | : The axe used to append the image for visualization. Can be 'x' (default),'y','z' or 'v'.
  | align | : Defines the relative alignment of images when displaying images of different sizes. Can be '`c'` (centered, which is the default), '`p'` (top alignment) and '`n'` (bottom aligment).

See also:
  CImg::append()

Definition at line 2004 of file CImg.h.

CImgDisplay& resize | ( | const CImg< T > & | img,
|  | const bool | redraw = `false`,
|  | const bool | force = `true`
| ) |

Resize a display window with the size of an image.

Parameters:

  | img | : Input image. `image.width` and `image.height` give the new dimensions of the display window.
  | redraw | : If `true` (default), the current displayed image in the display window will be bloc-interpolated to fit the new dimensions. If `false`, a black image will be drawn in the resized window.
  | force | : If `true`, the window size is effectively set to the specified dimensions (default). If `false`, only internal data buffer to display images is resized, not the window itself.

See also:
  CImgDisplay::resized, CImgDisplay::resizedimx(), CImgDisplay::resizedimy()

Definition at line 2017 of file CImg.h.

## Member Data Documentation

unsigned int width

Variable representing the width of the display.

Prefer using CImgDisplay::dimx() to get the width of the display.

Note:
  Using CImgDisplay::dimx() instead of `width` is more safe when doing arithmetics involving the value of `width`, since it returns a signed int. Arithmetics with unsigned types needs a lot of attention.

  The variable `width` should be considered as read-only. Setting a new value for `CImgDisplay::width` is done through CImgDisplay::resize(). Modifying directly `width` would probably result in a crash.

See also:
  CImgDisplay::height, CImgDisplay::resize()

Definition at line 1780 of file CImg.h.

unsigned int height

Variable representing the height of the display.

Prefer using CImgDisplay::dimy() to get the height of the display.

Note:
  Using CImgDisplay::dimy() instead of `height` is more safe when doing arithmetics involving the value of `height`, since it returns a signed int. Artihmetics with unsigned types needs a lot of attention.

  The variable `height` should be considered as read-only. Setting a new value for `CImgDisplay::height` is done through CImgDisplay::resize(). Modifying directly `height` would probably result in a crash.

See also:
  CImgDisplay::width, CImgDisplay::resize()

Definition at line 1796 of file CImg.h.

volatile unsigned int window_width

Variable representing the width of the window associated to the current display (should be considered as read-only).

Note:
  This is not the width of the display, but the width of the underlying system window. This variable is updated when an user resized the window associated to the display. When it occurs, `width` and `window_width` will be probably different.

See also:
  CImgDisplay::window_height, CImgDisplay::resized, CImgDisplay::resize().

Definition at line 1806 of file CImg.h.

volatile unsigned int window_height

Variable representing the height of the window associated to the current display (should be considered as read-only).

Note:
  This is not the height of the display, but the height of the underlying system window. This variable is updated when an user resized the window associated to the display. When it occurs, `height` and `window_height` will be probably different.

See also:
  CImgDisplay::window_width, CImgDisplay::resized, CImgDisplay::resize().

Definition at line 1816 of file CImg.h.

unsigned int normalization

Variable defining the pixel normalization behavior of the display window (can be modified on the fly).

It represents the way the pixel values are normalized for display purposes. Its value can be set to :

- `0` : No pixel value normalization are performed (fastest). Be sure your image data are bounded in [0,255].
- `1` : Pixel value renormalization between [0,255] is done at each display request (default).
- `2` : Pixel value renormalization between [0,255] is done at the first display request. Then the normalization parameters are kept and used for the next image display requests.
  Note:
    `normalization` is preferably set by invoking constructors CImgDisplay::CImgDisplay().
  See also:
    CImgDisplay::CImgDisplay(), CImgDisplay::display().

Definition at line 1829 of file CImg.h.

unsigned int events

Variable representing the type of events handled by the display window (should be considered as read-only).

It represents what events are handled by the display. Its value can be set to :

- `0` : No events are handled by the display.
- `1` : Display closing and resizing are handled by the display.
- `2` : Display closing, resizing, mouse motion and buttons press, as well as key press are handled by the display.
- `3` : Display closing, resizing, mouse motion and buttons press/release, as well as key press/release are handled by the display.
  Note:
    `events` if preferably set by invoking constructors CImgDisplay::CImgDisplay().
  See also:
    CImgDisplay::CImgDisplay(), CImgDisplay::mousex, CImgDisplay::mousey, CImgDisplay::key, CImgDisplay::button, CImgDisplay::resized, CImgDisplay::closed.

Definition at line 1843 of file CImg.h.

const bool fullscreen

Variable indicating if the display is fullscreen (should be considered as read-only).

If the display has been specified to be fullscreen at the construction, this variable is set to `true`.

Note:
  This is only useful for Windows-based OS. Fullscreen is not yet supported on X11-based systems and `fullscreen` will always be equal to false in this case.

Definition at line 1851 of file CImg.h.

volatile int mousex

Variable representing the current x-coordinate of the mouse pointer over the display window (should be considered as read-only).

If CImgDisplay::events>=2, `mousex` represents the current x-coordinate of the mouse pointer.

- If the mouse pointer is outside the display window, `mousex` is equal to `-1`.
- If the mouse pointer is over the display window, `mousex` falls in the range [0,CImgDisplay::width-1], where `0` corresponds to the far left coordinate and `CImgDisplay::width-1` to the far right coordinate.
  Note:
    `mousex` is updated every 25 milliseconds, through an internal thread.
  See also:
    CImgDisplay::mousey, CImgDisplay::button

Definition at line 1863 of file CImg.h.

volatile int mousey

Variable representing the current y-coordinate of the mouse pointer over the display window. (should be considered as read only).

If CImgDisplay::events>=2, `mousey` represents the current y-coordinate of the mouse pointer.

- If the mouse pointer is outside the display window, `mousey` is equal to `-1`.
- If the mouse pointer is over the display window, `mousey` falls in the range [0,CImgDisplay::height-1], where `0` corresponds to the far top coordinate and `CImgDisplay::height-1` to the far bottom coordinate.
  Note:
    `mousey` is updated every 25 milliseconds, through an internal thread.
  See also:
    CImgDisplay::mousex, CImgDisplay::button

Definition at line 1875 of file CImg.h.

volatile unsigned int button

Variable representing the state of the mouse buttons when the mouse pointer is over the display window. (should be considered as read only).

If CImgDisplay::events>=2, `button` represents the current state of the mouse buttons.

- If the mouse pointer is outside the display window, `button` is equal to `0`.
- If the mouse pointer is over the display window, `button` is a combination of the following bits :
- bit 0 : State of the left mouse button.
- bit 1 : State of the right mouse button.
- bit 2 : State of the middle mouse button.
- Other bits are unused.
  Note:
- `button` is updated every 25 milliseconds, through an internal thread.
- If CImgDisplay::events==2, you should re-init `button` to `0` after catching the mouse button events, since it will NOT be done automatically (`Mouse` `button` `Release` event is not handled in this case).
  See also:
    CImgDisplay::mousex, CImgDisplay::mousey

Definition at line 1894 of file CImg.h.

volatile unsigned int key

Variable representing the key pressed when mouse pointer is over the display window.

If CImgDisplay::events>=2, `key` represents a raw integer value corresponding to the current pressed key.

- If no keys are pressed, `key` is equal to `0`.
- If a key is pressed, `key` is a value representing the key. This raw value is OS-dependent. Testing the `key` value directly with a raw integer will mostly result in incompabilities between different plateforms. To bypass this problem, OS-independent keycodes are defined in the `cimg:`: namespace. They are named as `cimg::key*`, where * stands for the key name : `cimg::keyESC`, `cimg::keyF1`, `cimg::key0`, `cimg::keyA`, `cimg::keySPACE`, `cimg::keySHIFTLEFT`, etc...

             CImgDisplay disp(320,200,"Display");        // Create a display window with full events handling
             ...
             if (disp.key==cimg::keyESC) exit(0);        // Exit when pressing the ESC key.
             ...

Note:
  - `key` is updated every 25 milliseconds, through an internal thread.
  - If CImgDisplay::events==2, You should re-init the `key` variable to `0` after catching the `Key` `Pressed` event, since it will NOT be done automatically (Key Release event is handled only when `CImgDisplay::events>=3`).

See also:
  CImgDisplay::button, CImgDisplay::mousex, CImgDisplay::mousey

Definition at line 1922 of file CImg.h.

volatile bool closed

Variable representing the visibility state of the display window (should be read only).

`closed` can be either true or false :

- `false` : The window is visible.
- `true` : The window is hidden.

If CImgDisplay::events>=1, `closed` is set to `true` when the user try to close the display window. The way to set a value for `closed` is to use the functions :

- CImgDisplay::show(), to set `closed` to `false`.
- CImgDisplay::close(), to set `closed` to `true`.

Closing a display window DO NOT destroy the instance object. It simply hides the display window and set the variable `closed` to true. You are then free to decide what to do when this event occurs. For instance, the following code will re-open the window indefinitely when the user tries to close it :

           CImgDisplay disp(320,200,"Try to close me !");
           for (;; disp.wait()) if (disp.closed) disp.show();

Note:
  - `closed` is updated every 25 milliseconds, through an internal thread.

See also:
  CImgDisplay::show(), CImgDisplay::close().

Definition at line 1948 of file CImg.h.