skia/ext/convolver.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef SKIA_EXT_CONVOLVER_H_
   6 #define SKIA_EXT_CONVOLVER_H_
   7
   8 #include <cmath>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/cpu.h"
  13 #include "third_party/skia/include/core/SkSize.h"
  14 #include "third_party/skia/include/core/SkTypes.h"
  15
  16 // We can build SSE2 optimized versions for all x86 CPUs
  17 // except when building for the IOS emulator.
  18 #if defined(ARCH_CPU_X86_FAMILY) && !defined(OS_IOS)
  19 #define SIMD_SSE2 1
  20 #define SIMD_PADDING 8  // 8 * int16
  21 #endif
  22
  23 #if defined (ARCH_CPU_MIPS_FAMILY) && \
  24     defined(__mips_dsp) && (__mips_dsp_rev >= 2)
  25 #define SIMD_MIPS_DSPR2 1
  26 #endif
  27 // avoid confusion with Mac OS X's math library (Carbon)
  28 #if defined(__APPLE__)
  29 #undef FloatToFixed
  30 #undef FixedToFloat
  31 #endif
  32
  33 namespace skia {
  34
  35 // Represents a filter in one dimension. Each output pixel has one entry in this
  36 // object for the filter values contributing to it. You build up the filter
  37 // list by calling AddFilter for each output pixel (in order).
  38 //
  39 // We do 2-dimensional convolution by first convolving each row by one
  40 // ConvolutionFilter1D, then convolving each column by another one.
  41 //
  42 // Entries are stored in fixed point, shifted left by kShiftBits.
  43 class ConvolutionFilter1D {
  44  public:
  45   typedef short Fixed;
  46
  47   // The number of bits that fixed point values are shifted by.
  48   enum { kShiftBits = 14 };
  49
  50   SK_API ConvolutionFilter1D();
  51   SK_API ~ConvolutionFilter1D();
  52
  53   // Convert between floating point and our fixed point representation.
  54   static Fixed FloatToFixed(float f) {
  55     return static_cast<Fixed>(f * (1 << kShiftBits));
  56   }
  57   static unsigned char FixedToChar(Fixed x) {
  58     return static_cast<unsigned char>(x >> kShiftBits);
  59   }
  60   static float FixedToFloat(Fixed x) {
  61     // The cast relies on Fixed being a short, implying that on
  62     // the platforms we care about all (16) bits will fit into
  63     // the mantissa of a (32-bit) float.
  64     COMPILE_ASSERT(sizeof(Fixed) == 2, fixed_type_should_fit_in_float_mantissa);
  65     float raw = static_cast<float>(x);
  66     return ldexpf(raw, -kShiftBits);
  67   }
  68
  69   // Returns the maximum pixel span of a filter.
  70   int max_filter() const { return max_filter_; }
  71
  72   // Returns the number of filters in this filter. This is the dimension of the
  73   // output image.
  74   int num_values() const { return static_cast<int>(filters_.size()); }
  75
  76   // Appends the given list of scaling values for generating a given output
  77   // pixel. |filter_offset| is the distance from the edge of the image to where
  78   // the scaling factors start. The scaling factors apply to the source pixels
  79   // starting from this position, and going for the next |filter_length| pixels.
  80   //
  81   // You will probably want to make sure your input is normalized (that is,
  82   // all entries in |filter_values| sub to one) to prevent affecting the overall
  83   // brighness of the image.
  84   //
  85   // The filter_length must be > 0.
  86   //
  87   // This version will automatically convert your input to fixed point.
  88   SK_API void AddFilter(int filter_offset,
  89                         const float* filter_values,
  90                         int filter_length);
  91
  92   // Same as the above version, but the input is already fixed point.
  93   void AddFilter(int filter_offset,
  94                  const Fixed* filter_values,
  95                  int filter_length);
  96
  97   // Retrieves a filter for the given |value_offset|, a position in the output
  98   // image in the direction we're convolving. The offset and length of the
  99   // filter values are put into the corresponding out arguments (see AddFilter
 100   // above for what these mean), and a pointer to the first scaling factor is
 101   // returned. There will be |filter_length| values in this array.
 102   inline const Fixed* FilterForValue(int value_offset,
 103                                      int* filter_offset,
 104                                      int* filter_length) const {
 105     const FilterInstance& filter = filters_[value_offset];
 106     *filter_offset = filter.offset;
 107     *filter_length = filter.trimmed_length;
 108     if (filter.trimmed_length == 0) {
 109       return NULL;
 110     }
 111     return &filter_values_[filter.data_location];
 112   }
 113
 114   // Retrieves the filter for the offset 0, presumed to be the one and only.
 115   // The offset and length of the filter values are put into the corresponding
 116   // out arguments (see AddFilter). Note that |filter_legth| and
 117   // |specified_filter_length| may be different if leading/trailing zeros of the
 118   // original floating point form were clipped.
 119   // There will be |filter_length| values in the return array.
 120   // Returns NULL if the filter is 0-length (for instance when all floating
 121   // point values passed to AddFilter were clipped to 0).
 122   SK_API const Fixed* GetSingleFilter(int* specified_filter_length,
 123                                       int* filter_offset,
 124                                       int* filter_length) const;
 125
 126   inline void PaddingForSIMD() {
 127     // Padding |padding_count| of more dummy coefficients after the coefficients
 128     // of last filter to prevent SIMD instructions which load 8 or 16 bytes
 129     // together to access invalid memory areas. We are not trying to align the
 130     // coefficients right now due to the opaqueness of <vector> implementation.
 131     // This has to be done after all |AddFilter| calls.
 132 #ifdef SIMD_PADDING
 133     for (int i = 0; i < SIMD_PADDING; ++i)
 134       filter_values_.push_back(static_cast<Fixed>(0));
 135 #endif
 136   }
 137
 138  private:
 139   struct FilterInstance {
 140     // Offset within filter_values for this instance of the filter.
 141     int data_location;
 142
 143     // Distance from the left of the filter to the center. IN PIXELS
 144     int offset;
 145
 146     // Number of values in this filter instance.
 147     int trimmed_length;
 148
 149     // Filter length as specified. Note that this may be different from
 150     // 'trimmed_length' if leading/trailing zeros of the original floating
 151     // point form were clipped differently on each tail.
 152     int length;
 153   };
 154
 155   // Stores the information for each filter added to this class.
 156   std::vector<FilterInstance> filters_;
 157
 158   // We store all the filter values in this flat list, indexed by
 159   // |FilterInstance.data_location| to avoid the mallocs required for storing
 160   // each one separately.
 161   std::vector<Fixed> filter_values_;
 162
 163   // The maximum size of any filter we've added.
 164   int max_filter_;
 165 };
 166
 167 // Does a two-dimensional convolution on the given source image.
 168 //
 169 // It is assumed the source pixel offsets referenced in the input filters
 170 // reference only valid pixels, so the source image size is not required. Each
 171 // row of the source image starts |source_byte_row_stride| after the previous
 172 // one (this allows you to have rows with some padding at the end).
 173 //
 174 // The result will be put into the given output buffer. The destination image
 175 // size will be xfilter.num_values() * yfilter.num_values() pixels. It will be
 176 // in rows of exactly xfilter.num_values() * 4 bytes.
 177 //
 178 // |source_has_alpha| is a hint that allows us to avoid doing computations on
 179 // the alpha channel if the image is opaque. If you don't know, set this to
 180 // true and it will work properly, but setting this to false will be a few
 181 // percent faster if you know the image is opaque.
 182 //
 183 // The layout in memory is assumed to be 4-bytes per pixel in B-G-R-A order
 184 // (this is ARGB when loaded into 32-bit words on a little-endian machine).
 185 SK_API void BGRAConvolve2D(const unsigned char* source_data,
 186                            int source_byte_row_stride,
 187                            bool source_has_alpha,
 188                            const ConvolutionFilter1D& xfilter,
 189                            const ConvolutionFilter1D& yfilter,
 190                            int output_byte_row_stride,
 191                            unsigned char* output,
 192                            bool use_simd_if_possible);
 193
 194 // Does a 1D convolution of the given source image along the X dimension on
 195 // a single channel of the bitmap.
 196 //
 197 // The function uses the same convolution kernel for each pixel. That kernel
 198 // must be added to |filter| at offset 0. This is a most straightforward
 199 // implementation of convolution, intended chiefly for development purposes.
 200 SK_API void SingleChannelConvolveX1D(const unsigned char* source_data,
 201                                      int source_byte_row_stride,
 202                                      int input_channel_index,
 203                                      int input_channel_count,
 204                                      const ConvolutionFilter1D& filter,
 205                                      const SkISize& image_size,
 206                                      unsigned char* output,
 207                                      int output_byte_row_stride,
 208                                      int output_channel_index,
 209                                      int output_channel_count,
 210                                      bool absolute_values);
 211
 212 // Does a 1D convolution of the given source image along the Y dimension on
 213 // a single channel of the bitmap.
 214 SK_API void SingleChannelConvolveY1D(const unsigned char* source_data,
 215                                      int source_byte_row_stride,
 216                                      int input_channel_index,
 217                                      int input_channel_count,
 218                                      const ConvolutionFilter1D& filter,
 219                                      const SkISize& image_size,
 220                                      unsigned char* output,
 221                                      int output_byte_row_stride,
 222                                      int output_channel_index,
 223                                      int output_channel_count,
 224                                      bool absolute_values);
 225
 226 // Set up the |filter| instance with a gaussian kernel. |kernel_sigma| is the
 227 // parameter of gaussian. If |derivative| is true, the kernel will be that of
 228 // the first derivative. Intended for use with the two routines above.
 229 SK_API void SetUpGaussianConvolutionKernel(ConvolutionFilter1D* filter,
 230                                            float kernel_sigma,
 231                                            bool derivative);
 232
 233 }  // namespace skia
 234
 235 #endif  // SKIA_EXT_CONVOLVER_H_