Package ca.cgjennings.graphics.filters

Class AbstractConvolver

  • All Implemented Interfaces:
    java.awt.image.BufferedImageOp
    Direct Known Subclasses:
    ConvolveFilter, GaussianBlurFilter, SharpenFilter
    public abstract class AbstractConvolver
extends AbstractImagewiseFilter
    An abstract base class for filters that perform convolutions. Concrete subclasses are responsible for supplying the convolution kernel(s) by implementing getKernels(). (Separable convolutions can be implemented by returning a pair of kernels.)

    Additional methods modify the behaviour of the convolution. They have default implementations that return the following values:

    getEdgeHandling() determines how input pixels that fall off the edge of the source image are handled. The base class returns EdgeHandling.REPEAT.

    isAlphaPremultiplied() determines whether the alpha channel is premultiplied. The default is true. Subclasses may choose to override this if they are calling the integer array filtering method with pixel data that is already premultiplied.

    isAlphaFiltered() determines whether the alpha channel is retained after filtering. The default is true. If false, the alpha channel will be completely opaque after filtering.

    In-place filtering: Unless otherwise noted, filters based on this class support in-place filtering (the source and destination images can be the same).

    Since:
    3.0
    Author:
    Chris Jennings

    • Constructor Detail

      • AbstractConvolver

        public AbstractConvolver()

    • Method Detail

      • getEdgeHandling

        public EdgeHandling getEdgeHandling()
        Returns the edge handling mode used by the convolution.
        Returns:
        how the filter handles pixels that fall of the image edge

      • isAlphaPremultiplied

        public boolean isAlphaPremultiplied()
        Returns true if images with an alpha channel will automatically be converted to a premultiplied format during the convolution, and converted back afterward.
        Returns:
        true if images are premultiplied automatically

      • isAlphaFiltered

        public boolean isAlphaFiltered()
        Returns true if the alpha channel is filtered. If this returns false, the alpha channel is set to 255. For more complex channel value manipulation, see ChannelSwapFilter.
        Returns:
        true if the alpha channel is processed by the filter

      • getKernels

        protected abstract java.awt.image.Kernel[] getKernels()
        Returns the convolution kernel(s) that should be applied to execute this filter. Typically, array is either length one (non-separable) or length two (separable).
        Returns:
        an array of non-null convolution kernels

      • filter

        public int[] filter​(int[] source,
                    int[] destination,
                    int width,
                    int height)
        Description copied from class: AbstractImagewiseFilter
        Applies the filter to ARGB pixel data stored in an array. This method can be used during the internal processing of other filters.
        Overrides:
        filter in class AbstractImagewiseFilter
        Parameters:
        source - the source pixel data in ARGB format
        destination - the destination in which the filtered should be stored, may be null
        width - the width of the source image
        height - the height of the source image
        Returns:
        the array that holds the destination pixels

      • filterPixels

        protected void filterPixels​(int[] srcPixels,
                            int[] dstPixels,
                            int width,
                            int height,
                            int y0,
                            int rowsToFilter)
        Description copied from class: AbstractImagewiseFilter
        Filters a block of rows in the source image, placing the result in the corresponding rows in the destination image. The block of rows to be filtered runs from y0 to y0 + rows-1 (inclusive).
        Specified by:
        filterPixels in class AbstractImagewiseFilter
        Parameters:
        srcPixels - the pixel data for the source image
        dstPixels - the destination for output pixels
        width - the width of the image
        height - the height of the image
        y0 - the index of the first row to filter
        rowsToFilter - the number of rows to filter

      • workFactor

        protected float workFactor()
        Description copied from class: AbstractImagewiseFilter
        Returns a factor representing the amount of work performed by this filter relative to a filter that simply copies the source image by reading and writing each pixel. For example, a filter that implemented a 3x3 convolution might return the value 9. The work factor value helps determine when an image should be processed in parallel. (There is significant overhead involved in running a filter in parallel, so it is only worth doing if the image is relatively large or the amount of processing per pixel is relatively high.)

        Note: The work factor may vary depending on the current filter settings.

        Overrides:
        workFactor in class AbstractImagewiseFilter
        Returns:
        the approximate amount of work per pixel, relative to simply copying the pixel values