xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

[ Main ] [ News] [ Download ] [ Screenshots ] [ FAQ ] [ Tutorial ] [ Documentation ] [ Forum ] [ Chat ] [ Links ]

# CImgException Struct Reference

Instances of this class are thrown when errors occur during a CImg library function call. More...

Inherited by CImgArgumentException, CImgDisplayException, CImgInstanceException, CImgIOException, and CImgWarningException.

List of all members.

## Public Attributes
char | message [1024]
| Message associated with the error that thrown the exception.

## Detailed Description

Instances of this class are thrown when errors occur during a CImg library function call.

## Overview

CImgException is the base class of CImg exceptions. Exceptions are thrown by the CImg Library when an error occured in a CImg library function call. CImgException is seldom thrown itself. Children classes that specify the kind of error encountered are generally used instead. These sub-classes are :

- CImgInstanceException : Thrown when the instance associated to the called CImg function is not correctly defined. Generally, this exception is thrown when one tries to process empty images. The example below will throw a CImgInstanceException.

            CImg<float> img;        // Construct an empty image.
            img.blur(10);           // Try to blur the image.

- CImgArgumentException : Thrown when one of the arguments given to the called CImg function is not correct. Generally, this exception is thrown when arguments passed to the function are outside an admissible range of values. The example below will throw a CImgArgumentException.

            CImg<float> img(100,100,1,3);   // Define a 100x100 color image with float pixels.
            img = 0;                     // Try to fill pixels from the 0 pointer (invalid argument to operator=() ).

- CImgIOException : Thrown when an error occured when trying to load or save image files. The example below will throw a CImgIOException.

            CImg<float> img("file_doesnt_exist.jpg");    // Try to load a file that doesn't exist.

- CImgDisplayException : Thrown when an error occured when trying to display an image in a window. This exception is thrown when image display request cannot be satisfied.

The parent class CImgException may be thrown itself when errors that cannot be classified in one of the above type occur. It is recommended not to throw CImgExceptions yourself, since there are normally reserved to CImg Library functions. CImgInstanceException, CImgArgumentException, CImgIOException and CImgDisplayException are simple subclasses of CImgException and are thus not detailled more in this reference documentation.

## Exception handling

When an error occurs, the CImg Library first displays the error in a modal window. Then, it throws an instance of the corresponding exception class, generally leading the program to stop (this is the default behavior). You can bypass this default behavior by handling the exceptions yourself, using a code block `try { ... } catch() { ... }`. In this case, you can avoid the apparition of the modal window, by defining the environment variable `cimg_debug` to 0 before including the CImg header file. The example below shows how to cleanly handle CImg Library exceptions :

          #define cimg_debug 0     // Disable modal window in CImg exceptions.
          #define "CImg.h"
          int main() {
            try {
              ...; // Here, do what you want.
            }
            catch (CImgInstanceException &e) {
              std::fprintf(stderr,"CImg Library Error : %s",e.message);  // Display your own error message
              ...                                                        // Do what you want now.
            }
          }