Home

QtImageFilter Class Reference

The QtImageFilter class is an abstract interface for image filter implementations. More...

 #include <QtImageFilter>

Public Types

Public Functions


Detailed Description

The QtImageFilter class is an abstract interface for image filter implementations.

QtImageFilter is part of the QtImageFilters solution which by default supports many popular image filters, among these are gaussian blurring, embossing (see image below), sharpening, defocus, punch/pinch and convolution filters.

The documentation for the QtImageFilterFactory::createImageFilter() function provides a complete list of all the supported image filters.

An image filter can be configured by setting various options. The options are set by associating a value from the FilterOption enum with a QVariant value using the setOption() function. The option() function returns the variant value of the given FilterOption value, while the supportsOption() function determines whether the given FilterOption value is supported by this image filter.

The image filter's name and description can be retrieved using the name() and description() functions respectively.The apply() function is used by the QtImageFilters framework to apply the image filters.

Developers can extend the framework with their own custom image filters by deriving from the QtImageFilter class. For example, the code below implements a simple mirror filter:

 class MirrorFilter : public QtImageFilter {
 public:
     enum MirrorFilterOption {
         MirrorHorizontal = UserOption,
         MirrorVertical
     };

     MirrorFilter()
     {
         m_mirrorVertical = false;
         m_mirrorHorizontal = true;
     }

     QImage apply(const QImage &img, const QRect& clipRect /*= QRect()*/ ) const
     {
         Q_UNUSED(clipRect);
         return img.mirrored(m_mirrorHorizontal, m_mirrorVertical);
     }

     QString name() const { return QLatin1String("Mirror"); }

     QVariant option(int filteroption) const
     {
         switch ((MirrorFilterOption)filteroption) {
         case MirrorVertical:
             return QVariant(m_mirrorVertical);
         break;
         case MirrorHorizontal:
             return QVariant(m_mirrorHorizontal);
         break;
         default:
             break;
         }
         return QVariant();
     }

     bool setOption(int filteroption, const QVariant &value)
     {
         switch ((MirrorFilterOption)filteroption) {
             case MirrorVertical:
                 m_mirrorVertical = value.toBool();
             break;
             case MirrorHorizontal:
                 m_mirrorHorizontal = value.toBool();
             break;
             default:
                 break;
         }
         return true;
     }

     bool supportsOption(int option) const
     {
         bool supports = false;
         switch ((MirrorFilterOption)option) {
             case MirrorVertical:
             case MirrorHorizontal:
                 supports = true;
             break;
             default:
                 break;
         }
         return supports;
     }

     QString description() const { return QObject::tr("A simple mirroring filter."); }

 private:
     bool m_mirrorVertical;
     bool m_mirrorHorizontal;
 };

A custom image filter must implement the pure virtual apply() and name() functions. In addition, the custom mirror filter above reimplements the option(), setOption() and supportsOption() functions inherited from the QtImageFilter class. Custom image filters can be configured just like any other image filter. In addition, the mirror filter provides a description of itself by reimplementing the description() function.

Finally, our custom filter implements a MirrorFilterOption enum and a couple of private variables.

Before it can be used, a custom image filter must be registered using the QtImageFilterFactory class. Once it is registered, the filter can be created just like any other image filter, using the QtImageFilterFactory::createImageFilter() function.

See also QtImageFilterFactory.


Member Type Documentation

enum QtImageFilter::FilterOption

This enum describes the various configuring options that can be set on a filter.

ConstantValueDescription
QtImageFilter::FilterChannels1The color channel(s) to perform the filtering on. A string consisting of zero or one entity of each of the characters r,g,b,a.
QtImageFilter::FilterBorderPolicy2Describes the behavior of the convolution when the convolution stencil is not within the bounds of the image. For example, if the convolution stencil is a 5x5 grid, and its central element is positioned at the image coordinates (0, 0), then the topleft element of the stencil will reference the image coordinates (-2, -2), and the bottom-right element of the stencil will reference the image coordinates (2, 2). For this specific case the 2 left-most columns and 2 top-most rows in the stencil grid will be references to pixels that are outside the image coordinates. This option specifies how the filter should behave in these special conditions:
  • If the policy is set to "mirror", the pixels is chosen in such a way that the image is considered to be mirrored around its edges.
  • If the policy is set to "extend", the pixel value is chosen in such a way that the border colors of the image is considered to be extended infinitely.
  • If the policy is set to "wrap", the pixel value is chosen in such a way that the image is considered to be wrapped. This is optimal if you want to perform filtering on tiled images.
QtImageFilter::ConvolutionDivisor3An integer number.
QtImageFilter::ConvolutionBias4An integer number.
QtImageFilter::ConvolutionKernelMatrix5A QtConvolutionKernelMatrix matrix.
QtImageFilter::Radius6A double number.
QtImageFilter::Force8A double number.
QtImageFilter::Center7A QPointF object.
QtImageFilter::UserOption0x100The first option that can be used for application-specific purposes.

See also option(), setOption(), and supportsOption().


Member Function Documentation

QtImageFilter::~QtImageFilter ()   [virtual]

Destroys this image filter.

QImage QtImageFilter::apply ( const QImage & image, const QRect & clipRectangle = QRect() ) const   [pure virtual]

This function is used by the QtImageFilters framework to apply the filter on the given image, returning the resulting filtered image. The clipRectangle parameter delimits the area that is filtered.

This is a pure virtual function that must be implemented in derived classes. The format of the returned image should be the same as the input image format (unless documented otherwise).

QString QtImageFilter::description () const   [virtual]

Returns a brief description of the image filter, usually only one sentence.

See also name().

QString QtImageFilter::name () const   [pure virtual]

Returns the name of the filter which also is an unique identifier.

This is a pure virtual function that must be implemented in derived classes.

See also description().

QVariant QtImageFilter::option ( int filteroption ) const   [virtual]

Retrieves the variant value of the given filteroption.

See also setOption(), supportsOption(), and FilterOption.

bool QtImageFilter::setOption ( int filteroption, const QVariant & value )   [virtual]

Sets the given filteroption on this image filter, and returns true if the configuring succeeds.

The possible values for the value parameter depends on the given filter option. If value contain an illegal value, or if the filter does not support the given filteroption, the function returns false.

See also option(), supportsOption(), and FilterOption.

bool QtImageFilter::supportsOption ( int filteroption ) const   [virtual]

Returns true if the current image filter supports the given filteroption, otherwise returns false.

Reimplement this function to reflect the options that the image filter supports. The default implementation returns false.

See also setOption() and FilterOption.


Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Solutions