core/src/com/google/zxing/MonochromeBitmapSource.java

   1 /*
   2  * Copyright 2007 ZXing authors
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.google.zxing;
  18
  19 import com.google.zxing.common.BitArray;
  20
  21 /**
  22  * <p>Encapsulates a generic black-and-white bitmap -- a collection of pixels in two dimensions.
  23  * This unifies many possible representations, like AWT's <code>BufferedImage</code>.</p>
  24  *
  25  * @author srowen@google.com (Sean Owen)
  26  */
  27 public interface MonochromeBitmapSource {
  28
  29   /**
  30    * @param x horizontal offset, from left, of the pixel
  31    * @param y vertical offset, from top, of the pixel
  32    * @return true iff the pixel at (x,y) is black
  33    */
  34   boolean isBlack(int x, int y);
  35
  36   /**
  37    * <p>Returns an entire row of black/white pixels as an array of bits, where "true" means "black".
  38    * This is a sort of "bulk get" operation intended to enable efficient access in
  39    * certain situations.</p>
  40    *
  41    * @param y vertical offset, from top, of the row of pixels
  42    * @param row if not null, {@link BitArray} to write pixels into. If null, a new {@link BitArray}
  43    * is allocated and returned.
  44    * @param startX horizontal offset, from left, from which to start getting pixels
  45    * @param getWidth number of pixels to get from the row
  46    * @return {@link BitArray} representing the (subset of the) row of pixels. If row parameter
  47    *         was not null, it is returned.
  48    */
  49   BitArray getBlackRow(int y, BitArray row, int startX, int getWidth);
  50
  51   /**
  52    * @return height of underlying image
  53    */
  54   int getHeight();
  55
  56   /**
  57    * @return width of underlying image
  58    */
  59   int getWidth();
  60
  61   /**
  62    * Retrieves the luminance at the pixel x,y in the bitmap. This method is only used for estimating
  63    * the black point and implementing getBlackRow() - it is not meant for decoding.
  64    *
  65    * @param x The x coordinate in the image.
  66    * @param y The y coordinate in the image.
  67    * @return The luminance value between 0 and 255.
  68    */
  69   int getLuminance(int x, int y);
  70
  71   /**
  72    * Some implementations can be much more efficient by fetching an entire row of luminance data at
  73    * a time. This method should be called once per row before calling getLuminance().
  74    *
  75    * @param y The row to cache.
  76    */
  77   void cacheRowForLuminance(int y);
  78
  79   /**
  80    * <p>Estimates black point according to the given method, which is optionally parameterized by
  81    * a single int argument. For {@link BlackPointEstimationMethod#ROW_SAMPLING}, this
  82    * specifies the row to sample.</p>
  83    *
  84    * <p>The estimated value will be used in subsequent computations that rely on an estimated black
  85    * point.</p>
  86    *
  87    * @param method black point estimation method
  88    * @param argument method-specific argument
  89    */
  90   void estimateBlackPoint(BlackPointEstimationMethod method, int argument) throws ReaderException;
  91
  92   /**
  93    * @return {@link BlackPointEstimationMethod} representing last sampling method used
  94    */
  95   BlackPointEstimationMethod getLastEstimationMethod();
  96
  97   /**
  98    * <p>Optional operation which returns an implementation based on the same underlying
  99    * image, but which behaves as if the underlying image had been rotated 90 degrees
 100    * counterclockwise. This is useful in the context of 1D barcodes and the
 101    * {@link DecodeHintType#TRY_HARDER} decode hint, and is only intended to be
 102    * used in non-resource-constrained environments. Hence, implementations
 103    * of this class which are only used in resource-constrained mobile environments
 104    * don't have a need to implement this.</p>
 105    *
 106    * @throws IllegalArgumentException if not supported
 107    */
 108   MonochromeBitmapSource rotateCounterClockwise();
 109
 110   /**
 111    * @return true iff rotation is supported
 112    * @see #rotateCounterClockwise()
 113    */
 114   boolean isRotateSupported();
 115
 116 }