C++ Template Image Processing Library.    

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

CImgDisplay Struct Reference

Class that opens a window which can display CImg<T> images and handles 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 CImgDisplaywait (const unsigned int milliseconds) const
 Synchronized waiting function. Same as cimg::wait().
template<typename T>
CImgDisplaydisplay (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>
CImgDisplayresize (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.
CImgDisplayresize (const int width, const int height, const bool redraw=false, const bool force=true)
 Resize a display window with new dimensions width and height.
CImgDisplaymove (const int posx, const int posy)
 Move a display window at a specific location posx, posy.
 ~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>
CImgDisplaydisplay (const CImg< T > &img, const unsigned int ymin=0, const unsigned int ymax=-1)
 Display an image in a window.
CImgDisplaywait ()
 Wait for a window event.
CImgDisplayshow ()
 Show a closed display.
CImgDisplayclose ()
 Close a visible display.
CImgDisplaytitle (const char *title,...)
 Set the window title.

Static Public Member Functions

static const int screen_dimx ()
 Return the width of the screen resolution.
static const int screen_dimy ()
 Return the height of the screen resolution.

Public Attributes

unsigned int width
 Width of the display.
unsigned int height
 Height of the display.
volatile unsigned int window_width
 Width of the window containing the display.
volatile unsigned int window_height
 Height of the window containing the display.
volatile int window_x
 X-coordinate of the display, relative to screen coordinates.
volatile int window_y
 Y-coordinate of the display, relative to screen coordinates.
unsigned int normalization
 Type of pixel normalization done by the display.
unsigned int events
 Type of events handled by the display.
const bool fullscreen
 Flag indicating fullscreen mode.
volatile int mouse_x
 X-coordinate of the mouse pointer over the display.
volatile int mouse_y
 Y-coordinate of the mouse pointer over the display.
volatile unsigned int button
 (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

Class that opens a window which can display CImg<T> images and handles 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.


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.

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.

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.

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.


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

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

const CImgDisplay& wait const unsigned int  milliseconds  )  const
 

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

See also:
cimg::wait()

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::get_append()

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


Member Data Documentation

unsigned int width
 

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

unsigned int height
 

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

volatile unsigned int window_width
 

Width of the window containing the display.

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

volatile unsigned int window_height
 

Height of the window containing the display.

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

unsigned int normalization
 

Type of pixel normalization done by the display.

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

unsigned int events
 

Type of events handled by the display.

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

const bool fullscreen
 

Flag indicating fullscreen mode.

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.

volatile int mouse_x
 

X-coordinate of the mouse pointer over the display.

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

  • If the mouse pointer is outside the display window, mouse_x is equal to -1.
  • If the mouse pointer is over the display window, mouse_x 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:
    mouse_x is updated every 25 milliseconds, through an internal thread.
    See also:
    CImgDisplay::mouse_y, CImgDisplay::button

volatile int mouse_y
 

Y-coordinate of the mouse pointer over the display.

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

  • If the mouse pointer is outside the display window, mouse_y is equal to -1.
  • If the mouse pointer is over the display window, mouse_y 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:
    mouse_y is updated every 25 milliseconds, through an internal thread.
    See also:
    CImgDisplay::mouse_x, CImgDisplay::button

volatile unsigned int button
 

(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::mouse_x, CImgDisplay::mouse_y

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) std::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::mouse_x, CImgDisplay::mouse_y

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 :

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().
The CImg Library - C++ Template Image Processing Library