michael@0: // Copyright (c) 2012 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: #ifndef SK_CONVOLVER_H
michael@0: #define SK_CONVOLVER_H
michael@0: 
michael@0: #include "SkSize.h"
michael@0: #include "SkTypes.h"
michael@0: #include "SkTArray.h"
michael@0: 
michael@0: // avoid confusion with Mac OS X's math library (Carbon)
michael@0: #if defined(__APPLE__)
michael@0: #undef FloatToConvolutionFixed
michael@0: #undef ConvolutionFixedToFloat
michael@0: #endif
michael@0: 
michael@0: // Represents a filter in one dimension. Each output pixel has one entry in this
michael@0: // object for the filter values contributing to it. You build up the filter
michael@0: // list by calling AddFilter for each output pixel (in order).
michael@0: //
michael@0: // We do 2-dimensional convolution by first convolving each row by one
michael@0: // SkConvolutionFilter1D, then convolving each column by another one.
michael@0: //
michael@0: // Entries are stored in ConvolutionFixed point, shifted left by kShiftBits.
michael@0: class SkConvolutionFilter1D {
michael@0: public:
michael@0:     typedef short ConvolutionFixed;
michael@0: 
michael@0:     // The number of bits that ConvolutionFixed point values are shifted by.
michael@0:     enum { kShiftBits = 14 };
michael@0: 
michael@0:     SK_API SkConvolutionFilter1D();
michael@0:     SK_API ~SkConvolutionFilter1D();
michael@0: 
michael@0:     // Convert between floating point and our ConvolutionFixed point representation.
michael@0:     static ConvolutionFixed FloatToFixed(float f) {
michael@0:         return static_cast<ConvolutionFixed>(f * (1 << kShiftBits));
michael@0:     }
michael@0:     static unsigned char FixedToChar(ConvolutionFixed x) {
michael@0:         return static_cast<unsigned char>(x >> kShiftBits);
michael@0:     }
michael@0:     static float FixedToFloat(ConvolutionFixed x) {
michael@0:         // The cast relies on ConvolutionFixed being a short, implying that on
michael@0:         // the platforms we care about all (16) bits will fit into
michael@0:         // the mantissa of a (32-bit) float.
michael@0:         SK_COMPILE_ASSERT(sizeof(ConvolutionFixed) == 2, ConvolutionFixed_type_should_fit_in_float_mantissa);
michael@0:         float raw = static_cast<float>(x);
michael@0:         return ldexpf(raw, -kShiftBits);
michael@0:     }
michael@0: 
michael@0:     // Returns the maximum pixel span of a filter.
michael@0:     int maxFilter() const { return fMaxFilter; }
michael@0: 
michael@0:     // Returns the number of filters in this filter. This is the dimension of the
michael@0:     // output image.
michael@0:     int numValues() const { return static_cast<int>(fFilters.count()); }
michael@0: 
michael@0:     // Appends the given list of scaling values for generating a given output
michael@0:     // pixel. |filterOffset| is the distance from the edge of the image to where
michael@0:     // the scaling factors start. The scaling factors apply to the source pixels
michael@0:     // starting from this position, and going for the next |filterLength| pixels.
michael@0:     //
michael@0:     // You will probably want to make sure your input is normalized (that is,
michael@0:     // all entries in |filterValuesg| sub to one) to prevent affecting the overall
michael@0:     // brighness of the image.
michael@0:     //
michael@0:     // The filterLength must be > 0.
michael@0:     //
michael@0:     // This version will automatically convert your input to ConvolutionFixed point.
michael@0:     SK_API void AddFilter(int filterOffset,
michael@0:                           const float* filterValues,
michael@0:                           int filterLength);
michael@0: 
michael@0:     // Same as the above version, but the input is already ConvolutionFixed point.
michael@0:     void AddFilter(int filterOffset,
michael@0:                    const ConvolutionFixed* filterValues,
michael@0:                    int filterLength);
michael@0: 
michael@0:     // Retrieves a filter for the given |valueOffset|, a position in the output
michael@0:     // image in the direction we're convolving. The offset and length of the
michael@0:     // filter values are put into the corresponding out arguments (see AddFilter
michael@0:     // above for what these mean), and a pointer to the first scaling factor is
michael@0:     // returned. There will be |filterLength| values in this array.
michael@0:     inline const ConvolutionFixed* FilterForValue(int valueOffset,
michael@0:                                        int* filterOffset,
michael@0:                                        int* filterLength) const {
michael@0:         const FilterInstance& filter = fFilters[valueOffset];
michael@0:         *filterOffset = filter.fOffset;
michael@0:         *filterLength = filter.fTrimmedLength;
michael@0:         if (filter.fTrimmedLength == 0) {
michael@0:             return NULL;
michael@0:         }
michael@0:         return &fFilterValues[filter.fDataLocation];
michael@0:     }
michael@0: 
michael@0:   // Retrieves the filter for the offset 0, presumed to be the one and only.
michael@0:   // The offset and length of the filter values are put into the corresponding
michael@0:   // out arguments (see AddFilter). Note that |filterLegth| and
michael@0:   // |specifiedFilterLength| may be different if leading/trailing zeros of the
michael@0:   // original floating point form were clipped.
michael@0:   // There will be |filterLength| values in the return array.
michael@0:   // Returns NULL if the filter is 0-length (for instance when all floating
michael@0:   // point values passed to AddFilter were clipped to 0).
michael@0:     SK_API const ConvolutionFixed* GetSingleFilter(int* specifiedFilterLength,
michael@0:         int* filterOffset,
michael@0:         int* filterLength) const;
michael@0: 
michael@0:     // Add another value to the fFilterValues array -- useful for
michael@0:     // SIMD padding which happens outside of this class.
michael@0: 
michael@0:     void addFilterValue( ConvolutionFixed val ) {
michael@0:         fFilterValues.push_back( val );
michael@0:     }
michael@0: private:
michael@0:     struct FilterInstance {
michael@0:         // Offset within filterValues for this instance of the filter.
michael@0:         int fDataLocation;
michael@0: 
michael@0:         // Distance from the left of the filter to the center. IN PIXELS
michael@0:         int fOffset;
michael@0: 
michael@0:         // Number of values in this filter instance.
michael@0:         int fTrimmedLength;
michael@0: 
michael@0:         // Filter length as specified. Note that this may be different from
michael@0:         // 'trimmed_length' if leading/trailing zeros of the original floating
michael@0:         // point form were clipped differently on each tail.
michael@0:         int fLength;
michael@0:     };
michael@0: 
michael@0:     // Stores the information for each filter added to this class.
michael@0:     SkTArray<FilterInstance> fFilters;
michael@0: 
michael@0:     // We store all the filter values in this flat list, indexed by
michael@0:     // |FilterInstance.data_location| to avoid the mallocs required for storing
michael@0:     // each one separately.
michael@0:     SkTArray<ConvolutionFixed> fFilterValues;
michael@0: 
michael@0:     // The maximum size of any filter we've added.
michael@0:     int fMaxFilter;
michael@0: };
michael@0: 
michael@0: typedef void (*SkConvolveVertically_pointer)(
michael@0:     const SkConvolutionFilter1D::ConvolutionFixed* filterValues,
michael@0:     int filterLength,
michael@0:     unsigned char* const* sourceDataRows,
michael@0:     int pixelWidth,
michael@0:     unsigned char* outRow,
michael@0:     bool hasAlpha);
michael@0: typedef void (*SkConvolve4RowsHorizontally_pointer)(
michael@0:     const unsigned char* srcData[4],
michael@0:     const SkConvolutionFilter1D& filter,
michael@0:     unsigned char* outRow[4]);
michael@0: typedef void (*SkConvolveHorizontally_pointer)(
michael@0:     const unsigned char* srcData,
michael@0:     const SkConvolutionFilter1D& filter,
michael@0:     unsigned char* outRow,
michael@0:     bool hasAlpha);
michael@0: typedef void (*SkConvolveFilterPadding_pointer)(
michael@0:     SkConvolutionFilter1D* filter);
michael@0: 
michael@0: struct SkConvolutionProcs {
michael@0:   // This is how many extra pixels may be read by the
michael@0:   // conolve*horizontally functions.
michael@0:     int fExtraHorizontalReads;
michael@0:     SkConvolveVertically_pointer fConvolveVertically;
michael@0:     SkConvolve4RowsHorizontally_pointer fConvolve4RowsHorizontally;
michael@0:     SkConvolveHorizontally_pointer fConvolveHorizontally;
michael@0:     SkConvolveFilterPadding_pointer fApplySIMDPadding;
michael@0: };
michael@0: 
michael@0: 
michael@0: 
michael@0: // Does a two-dimensional convolution on the given source image.
michael@0: //
michael@0: // It is assumed the source pixel offsets referenced in the input filters
michael@0: // reference only valid pixels, so the source image size is not required. Each
michael@0: // row of the source image starts |sourceByteRowStride| after the previous
michael@0: // one (this allows you to have rows with some padding at the end).
michael@0: //
michael@0: // The result will be put into the given output buffer. The destination image
michael@0: // size will be xfilter.numValues() * yfilter.numValues() pixels. It will be
michael@0: // in rows of exactly xfilter.numValues() * 4 bytes.
michael@0: //
michael@0: // |sourceHasAlpha| is a hint that allows us to avoid doing computations on
michael@0: // the alpha channel if the image is opaque. If you don't know, set this to
michael@0: // true and it will work properly, but setting this to false will be a few
michael@0: // percent faster if you know the image is opaque.
michael@0: //
michael@0: // The layout in memory is assumed to be 4-bytes per pixel in B-G-R-A order
michael@0: // (this is ARGB when loaded into 32-bit words on a little-endian machine).
michael@0: SK_API void BGRAConvolve2D(const unsigned char* sourceData,
michael@0:     int sourceByteRowStride,
michael@0:     bool sourceHasAlpha,
michael@0:     const SkConvolutionFilter1D& xfilter,
michael@0:     const SkConvolutionFilter1D& yfilter,
michael@0:     int outputByteRowStride,
michael@0:     unsigned char* output,
michael@0:     const SkConvolutionProcs&,
michael@0:     bool useSimdIfPossible);
michael@0: 
michael@0: #endif  // SK_CONVOLVER_H