juce/source/src/gui/graphics/imaging/juce_ImageConvolutionKernel.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_IMAGECONVOLUTIONKERNEL_JUCEHEADER__
  27 #define __JUCE_IMAGECONVOLUTIONKERNEL_JUCEHEADER__
  28
  29 #include "juce_Image.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     Represents a filter kernel to use in convoluting an image.
  35
  36     @see Image::applyConvolution
  37 */
  38 class JUCE_API  ImageConvolutionKernel
  39 {
  40 public:
  41     //==============================================================================
  42     /** Creates an empty convulution kernel.
  43
  44         @param size     the length of each dimension of the kernel, so e.g. if the size
  45                         is 5, it will create a 5x5 kernel
  46     */
  47     ImageConvolutionKernel (int size);
  48
  49     /** Destructor. */
  50     ~ImageConvolutionKernel();
  51
  52     //==============================================================================
  53     /** Resets all values in the kernel to zero. */
  54     void clear();
  55
  56     /** Returns one of the kernel values. */
  57     float getKernelValue (int x, int y) const noexcept;
  58
  59     /** Sets the value of a specific cell in the kernel.
  60
  61         The x and y parameters must be in the range 0 < x < getKernelSize().
  62
  63         @see setOverallSum
  64     */
  65     void setKernelValue (int x, int y, float value) noexcept;
  66
  67     /** Rescales all values in the kernel to make the total add up to a fixed value.
  68
  69         This will multiply all values in the kernel by (desiredTotalSum / currentTotalSum).
  70     */
  71     void setOverallSum (float desiredTotalSum);
  72
  73     /** Multiplies all values in the kernel by a value. */
  74     void rescaleAllValues (float multiplier);
  75
  76     /** Intialises the kernel for a gaussian blur.
  77
  78         @param blurRadius   this may be larger or smaller than the kernel's actual
  79                             size but this will obviously be wasteful or clip at the
  80                             edges. Ideally the kernel should be just larger than
  81                             (blurRadius * 2).
  82     */
  83     void createGaussianBlur (float blurRadius);
  84
  85     //==============================================================================
  86     /** Returns the size of the kernel.
  87
  88         E.g. if it's a 3x3 kernel, this returns 3.
  89     */
  90     int getKernelSize() const               { return size; }
  91
  92     //==============================================================================
  93     /** Applies the kernel to an image.
  94
  95         @param destImage        the image that will receive the resultant convoluted pixels.
  96         @param sourceImage      the source image to read from - this can be the same image as
  97                                 the destination, but if different, it must be exactly the same
  98                                 size and format.
  99         @param destinationArea  the region of the image to apply the filter to
 100     */
 101     void applyToImage (Image& destImage,
 102                        const Image& sourceImage,
 103                        const Rectangle<int>& destinationArea) const;
 104
 105 private:
 106     //==============================================================================
 107     HeapBlock <float> values;
 108     const int size;
 109
 110     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ImageConvolutionKernel);
 111 };
 112
 113
 114 #endif   // __JUCE_IMAGECONVOLUTIONKERNEL_JUCEHEADER__