summaryrefslogtreecommitdiff
path: root/backend/pixma.h
diff options
context:
space:
mode:
Diffstat (limited to 'backend/pixma.h')
-rw-r--r--backend/pixma.h490
1 files changed, 490 insertions, 0 deletions
diff --git a/backend/pixma.h b/backend/pixma.h
new file mode 100644
index 0000000..56bd14d
--- /dev/null
+++ b/backend/pixma.h
@@ -0,0 +1,490 @@
+/* SANE - Scanner Access Now Easy.
+
+ Copyright (C) 2007-2008 Nicolas Martin, <nicols-guest at alioth dot debian dot org>
+ Copyright (C) 2006-2007 Wittawat Yamwong <wittawat@web.de>
+ Copyright (C) 2011-2013 Rolf Bensch <rolf at bensch hyphen online dot de>
+
+ This file is part of the SANE package.
+
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 2 of the
+ License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ MA 02111-1307, USA.
+
+ As a special exception, the authors of SANE give permission for
+ additional uses of the libraries contained in this release of SANE.
+
+ The exception is that, if you link a SANE library with other files
+ to produce an executable, this does not by itself cause the
+ resulting executable to be covered by the GNU General Public
+ License. Your use of that executable is in no way restricted on
+ account of linking the SANE library code into it.
+
+ This exception does not, however, invalidate any other reasons why
+ the executable file might be covered by the GNU General Public
+ License.
+
+ If you submit changes to SANE to the maintainers to be included in
+ a subsequent release, you agree by submitting the changes that
+ those changes may be distributed with this exception intact.
+
+ If you write modifications of your own for SANE, it is your choice
+ whether to permit this exception to apply to your modifications.
+ If you do not wish that, delete this exception notice.
+ */
+#ifndef PIXMA_H
+#define PIXMA_H
+
+/*!
+ * \mainpage Scanner driver for Canon PIXMA MP series
+ * \section example Sample code for application
+ * \code
+ * pixma_set_debug_level(level);
+ * pixma_init();
+ * nscanners = pixma_find_scanners();
+ * devnr = choose_scanner(nscanners);
+ * scanner = pixma_open(devnr);
+ * setup_param(param);
+ * pixma_check_scan_param(scanner, param);
+ * do {
+ * if (I_need_events &&
+ * (ev = pixma_wait_event(scanner, timeout)) > 0) {
+ * handle_event(ev);
+ * }
+ * pixma_scan(scanner, param);
+ * while ((count = pixma_read_image(scanner, buf, len)) > 0) {
+ * write(buf, count);
+ * if (error_occured_in_write) {
+ * pixma_cancel(scanner);
+ * }
+ * }
+ * } while (!enough);
+ * pixma_close(scanner);
+ * pixma_cleanup();
+ * \endcode
+ *
+ * <b>Note:</b> pixma_cancel() can be called asynchronously to
+ * interrupt pixma_read_image(). It does not cancel the operation
+ * immediately. pixma_read_image() <em>must</em> be called until it
+ * returns zero or an error (probably \c PIXMA_ECANCELED).
+ *
+ * \section reference Reference
+ * - \subpage API
+ * - \subpage IO
+ * - \subpage subdriver
+ * - \subpage debug
+ */
+
+/*!
+ * \defgroup API The driver API
+ * \brief The driver API.
+ *
+ * The return value of functions that returns \c int has the following
+ * meaning if not otherwise specified:
+ * - >= 0 if succeeded
+ * - < 0 if failed
+ */
+
+#ifdef HAVE_STDINT_H
+# include <stdint.h> /* available in ISO C99 */
+#else
+# include <sys/types.h>
+typedef uint8_t uint8_t;
+typedef uint16_t uint16_t;
+typedef uint32_t uint32_t;
+#endif /* HAVE_STDINT_H */
+
+#ifdef HAVE_INTTYPES_H
+# include <inttypes.h> /* available in ISO C99 */
+#endif /* HAVE_INTTYPES_H */
+
+/** \addtogroup API
+ * @{ */
+/** \name Version of the driver */
+/**@{*/
+#define PIXMA_VERSION_MAJOR 0
+#define PIXMA_VERSION_MINOR 17
+#define PIXMA_VERSION_BUILD 4
+/**@}*/
+
+/** \name Error codes */
+/**@{*/
+#define PIXMA_EIO -1
+#define PIXMA_ENODEV -2
+#define PIXMA_EACCES -3
+#define PIXMA_ENOMEM -4
+#define PIXMA_EINVAL -5
+#define PIXMA_EBUSY -6
+#define PIXMA_ECANCELED -7
+#define PIXMA_ENOTSUP -8
+#define PIXMA_ETIMEDOUT -9
+#define PIXMA_EPROTO -10
+#define PIXMA_EPAPER_JAMMED -11
+#define PIXMA_ECOVER_OPEN -12
+#define PIXMA_ENO_PAPER -13
+#define PIXMA_EOF -14
+/**@}*/
+
+/** \name Capabilities for using with pixma_config_t::cap */
+/**@{*/
+#define PIXMA_CAP_EASY_RGB (1 << 0)
+#define PIXMA_CAP_GRAY (1 << 1)
+#define PIXMA_CAP_ADF (1 << 2)
+#define PIXMA_CAP_48BIT (1 << 3)
+#define PIXMA_CAP_GAMMA_TABLE (1 << 4)
+#define PIXMA_CAP_EVENTS (1 << 5)
+#define PIXMA_CAP_TPU (1 << 6)
+#define PIXMA_CAP_ADFDUP ((1 << 7) | PIXMA_CAP_ADF)
+#define PIXMA_CAP_CIS (0)
+#define PIXMA_CAP_CCD (1 << 8)
+#define PIXMA_CAP_LINEART (1 << 9)
+#define PIXMA_CAP_NEGATIVE (1 << 10)
+#define PIXMA_CAP_TPUIR ((1 << 11) | PIXMA_CAP_TPU)
+#define PIXMA_CAP_EXPERIMENT (1 << 31)
+/**@}*/
+
+/** \name Button events and related information returned by pixma_wait_event() */
+/**@{*/
+#define PIXMA_EV_NONE 0
+#define PIXMA_EV_ACTION_MASK (0xffffff)
+#define PIXMA_EV_BUTTON1 (1 << 24)
+#define PIXMA_EV_BUTTON2 (2 << 24)
+#define PIXMA_EV_TARGET_MASK (0xff)
+#define PIXMA_EV_ORIGINAL_MASK (0xff00)
+#define PIXMA_EV_DPI_MASK (0xff0000)
+
+#define GET_EV_TARGET(x) (x & PIXMA_EV_TARGET_MASK)
+#define GET_EV_ORIGINAL(x) ( (x & PIXMA_EV_ORIGINAL_MASK) >> 8 )
+#define GET_EV_DPI(x) ( (x & PIXMA_EV_DPI_MASK) >> 16 )
+
+/**@}*/
+/** @} end of API group */
+
+#define PIXMA_CONFIG_FILE "pixma.conf"
+#define MAX_CONF_DEVICES 15
+
+struct pixma_t;
+struct pixma_scan_ops_t;
+struct pixma_scan_param_t;
+struct pixma_config_t;
+struct pixma_cmdbuf_t;
+struct pixma_imagebuf_t;
+struct pixma_device_status_t;
+
+typedef struct pixma_t pixma_t;
+typedef struct pixma_scan_ops_t pixma_scan_ops_t;
+typedef struct pixma_scan_param_t pixma_scan_param_t;
+typedef struct pixma_config_t pixma_config_t;
+typedef struct pixma_cmdbuf_t pixma_cmdbuf_t;
+typedef struct pixma_imagebuf_t pixma_imagebuf_t;
+typedef struct pixma_device_status_t pixma_device_status_t;
+
+
+/** \addtogroup API
+ * @{ */
+/** String index constants */
+typedef enum pixma_string_index_t
+{
+ PIXMA_STRING_MODEL,
+ PIXMA_STRING_ID,
+ PIXMA_STRING_LAST
+} pixma_string_index_t;
+
+/** Paper sources */
+typedef enum pixma_paper_source_t
+{
+ PIXMA_SOURCE_FLATBED,
+ PIXMA_SOURCE_ADF,
+ PIXMA_SOURCE_TPU,
+ PIXMA_SOURCE_ADFDUP /* duplex */
+} pixma_paper_source_t;
+
+/** Scan modes */
+typedef enum pixma_scan_mode_t
+{
+ /* standard scan modes */
+ PIXMA_SCAN_MODE_COLOR,
+ PIXMA_SCAN_MODE_GRAY,
+ /* TPU scan modes for negatives */
+ PIXMA_SCAN_MODE_NEGATIVE_COLOR,
+ PIXMA_SCAN_MODE_NEGATIVE_GRAY,
+ /* extended scan modes for 48 bit flatbed scanners */
+ PIXMA_SCAN_MODE_COLOR_48,
+ PIXMA_SCAN_MODE_GRAY_16,
+ /* 1 bit lineart scan mode */
+ PIXMA_SCAN_MODE_LINEART,
+ /* TPUIR scan mode */
+ PIXMA_SCAN_MODE_TPUIR
+} pixma_scan_mode_t;
+
+typedef enum pixma_hardware_status_t
+{
+ PIXMA_HARDWARE_OK,
+ PIXMA_HARDWARE_ERROR
+} pixma_hardware_status_t;
+
+typedef enum pixma_lamp_status_t
+{
+ PIXMA_LAMP_OK,
+ PIXMA_LAMP_WARMING_UP,
+ PIXMA_LAMP_OFF,
+ PIXMA_LAMP_ERROR
+} pixma_lamp_status_t;
+
+typedef enum pixma_adf_status_t
+{
+ PIXMA_ADF_OK,
+ PIXMA_ADF_NO_PAPER,
+ PIXMA_ADF_JAMMED,
+ PIXMA_ADF_COVER_OPEN,
+ PIXMA_ADF_ERROR
+} pixma_adf_status_t;
+
+typedef enum pixma_calibration_status_t
+{
+ PIXMA_CALIBRATION_OK,
+ PIXMA_CALIBRATION_IN_PROGRESS,
+ PIXMA_CALIBRATION_OFF,
+ PIXMA_CALIBRATION_ERROR
+} pixma_calibration_status_t;
+
+/** Device status. */
+struct pixma_device_status_t
+{
+ pixma_hardware_status_t hardware;
+ pixma_lamp_status_t lamp;
+ pixma_adf_status_t adf;
+ pixma_calibration_status_t cal;
+};
+
+/** Scan parameters. */
+struct pixma_scan_param_t
+{
+ /** Size in bytes of one image line (row).
+ * line_size >= depth / 8 * channels * w <br>
+ * This field will be set by pixma_check_scan_param(). */
+ uint64_t line_size;
+
+ /** Size in bytes of the whole image.
+ * image_size = line_size * h <br>
+ * This field will be set by pixma_check_scan_param(). */
+ uint64_t image_size;
+
+ /** Channels per pixel. 1 = grayscale and lineart, 3 = color */
+ unsigned channels;
+
+ /** Bits per channels.
+ * 1 = 1 bit B/W lineart (flatbed)
+ * 8 = 8 bit grayscale,
+ * 24 bit color (both flatbed)
+ * 16 = 16 bit grayscale (TPU, flatbed not implemeted),
+ * 48 bit color (TPU, flatbed not implemented) */
+ unsigned depth;
+
+ /*@{ */
+ /** Resolution. Valid values are 75,150,300,600,1200... */
+ unsigned xdpi, ydpi;
+ /*@} */
+
+ /*! \name Scan area in pixels
+ * (0,0) = top left; positive x extends to the right; positive y to the
+ * bottom; in pixels.
+ * xs is the offset in x direction of the selected scan range relative
+ * to the range read from the scanner and wx the width in x direction
+ * of the scan line read from scanner. */
+ /*@{ */
+ unsigned x, y, w, h, xs, wx;
+ /*@} */
+
+ /** Flag indicating whether the offset correction for TPU scans
+ * was already performed (to avoid repeated corrections).
+ * Currently only used in pixma_mp810.c sub-driver */
+ unsigned tpu_offset_added;
+
+ /** Flag indicating whether a software-lineart scan is in progress
+ * 0 = other scan
+ * 1 = software-lineart scan */
+ unsigned software_lineart;
+
+ /** Threshold for software-lineart scans */
+ unsigned threshold;
+
+ /** lineart threshold curve for dynamic rasterization */
+ unsigned threshold_curve;
+
+ /* look up table used in dynamic rasterization */
+ unsigned char lineart_lut[256];
+
+ /** Gamma table. 4096 entries, 12 bit => 8 bit. If \c NULL, default gamma
+ * specified by subdriver will be used. */
+ const uint8_t *gamma_table;
+
+ /** \see #pixma_paper_source_t */
+ pixma_paper_source_t source;
+
+ /** \see #pixma_scan_mode_t */
+ pixma_scan_mode_t mode;
+
+ /** The current page # in the same ADF scan session, 0 in non ADF */
+ unsigned adf_pageid;
+};
+
+/** PIXMA model information */
+struct pixma_config_t
+{
+ /* If you change this structure, don't forget to update the device list in
+ * subdrivers. */
+ const char *name; /**< Model name. */
+ const char *model; /**< Short model */
+ uint16_t vid; /**< USB Vendor ID */
+ uint16_t pid; /**< USB Product ID */
+ unsigned iface; /**< USB Interface number */
+ const pixma_scan_ops_t *ops; /**< Subdriver ops */
+ unsigned xdpi; /**< Maximum horizontal resolution[DPI] */
+ unsigned ydpi; /**< Maximum vertical resolution[DPI] */
+ unsigned adftpu_min_dpi; /**< Maximum horizontal resolution[DPI] for adf/tpu
+ * only needed if ADF/TPU has another min. dpi value than 75 dpi */
+ unsigned adftpu_max_dpi; /**< Maximum vertical resolution[DPI] for adf/tpu
+ * only needed if ADF/TPU has another max. dpi value than xdpi */
+ unsigned tpuir_min_dpi; /**< Minimum resolution[DPI] for tpu-ir
+ * only needed if TPU-IR has another min. dpi value than 75 dpi */
+ unsigned tpuir_max_dpi; /**< Maximum resolution[DPI] for tpu-ir
+ * only needed if TPU-IR has another max. dpi value than xdpi */
+ unsigned width; /**< Maximum width of scannable area in pixels at 75DPI */
+ unsigned height; /**< Maximum height of scannable area in pixels at 75DPI */
+ unsigned cap; /**< Capability bitfield \see PIXMA_CAP_* */
+};
+
+
+/* Defined in pixma_common.c */
+
+/** Initialize the driver. It must be called before any other functions
+ * except pixma_set_debug_level(). */
+int pixma_init (void);
+
+/** Free resources allocated by the driver. */
+void pixma_cleanup (void);
+
+/** Set the debug level.
+ * \param[in] level the debug level
+ * - 0 No debug output at all
+ * - 1 Only errors and warning
+ * - 2 General information
+ * - 3 Debugging messages
+ * - 10 USB traffic dump */
+void pixma_set_debug_level (int level);
+
+/** Find scanners. The device number used in pixma_open(),
+ * pixma_get_device_model(), pixma_get_device_id() and
+ * pixma_get_device_config() must be less than the value returned by the last
+ * call of this function.
+ *
+ * \return The number of scanners found currently. The return value is
+ * guaranteed to be valid until the next call to pixma_find_scanners(). */
+int pixma_find_scanners (const char **conf_devices);
+
+/** Return the model name of the device \a devnr. */
+const char *pixma_get_device_model (unsigned devnr);
+
+/** Return the unique ID of the device \a devnr. */
+const char *pixma_get_device_id (unsigned devnr);
+
+/** Return the device configuration of the device \a devnr. */
+const struct pixma_config_t *pixma_get_device_config (unsigned devnr);
+
+/** Open a connection to the scanner \a devnr.
+ * \param[in] devnr The scanner number
+ * \param[out] handle The device handle
+ * \see pixma_find_scanners() */
+int pixma_open (unsigned devnr, pixma_t ** handle);
+
+/** Close the connection to the scanner. The scanning process is aborted
+ * if necessary before the function returns. */
+void pixma_close (pixma_t * s);
+
+/** Initiate an image acquisition process. You must keep \a sp valid until the
+ * image acquisition process has finished. */
+int pixma_scan (pixma_t *, pixma_scan_param_t * sp);
+
+/** Read a block of image data. It blocks until there is at least one byte
+ * available or an error occurs.
+ *
+ * \param[out] buf Pointer to the buffer
+ * \param[in] len Size of the buffer
+ *
+ * \retval count Number of bytes written to the buffer or error. Possible
+ * return value:
+ * - count = 0 for end of image
+ * - count = \a len
+ * - 0 < count < \a len if and only if it is the last block.
+ * - count < 0 for error */
+int pixma_read_image (pixma_t *, void *buf, unsigned len);
+
+#if 0
+/** Read a block of image data and write to \a fd.
+ * \param[in] fd output file descriptor
+ * \see pixma_read_image() */
+int pixma_read_image_write (pixma_t *, int fd);
+#endif
+
+/** Cancel the scanning process. No effect if no scanning process is in
+ * progress. It can be called asynchronously e.g. within a signal
+ * handle. pixma_cancel() doesn't abort the operation immediately. It
+ * guarantees that the current call or, at the latest, the next call to
+ * pixma_read_image() will return zero or an error (probably PIXMA_ECANCELED). */
+void pixma_cancel (pixma_t *);
+
+/** Check the scan parameters. This function can change your parameters to
+ * match the device capability, e.g. adjust width and height to the available
+ * area.
+ * \return PIXMA_EINVAL for invalid parameters. */
+int pixma_check_scan_param (pixma_t *, pixma_scan_param_t *);
+
+/** Wait until a scanner button is pressed or it times out. It should not be
+ * called during image acquisition is in progress.
+ * \param[in] timeout in milliseconds, less than 0 means forever
+ * \return
+ * - \c PIXMA_EV_NONE if it timed out.
+ * - non-zero value indicates which button was pressed.
+ * \see PIXMA_EV_*
+ */
+uint32_t pixma_wait_event (pixma_t *, int timeout);
+
+/** Activate connection to scanner */
+int pixma_activate_connection (pixma_t *);
+
+/** De-activate connection to scanner */
+
+int pixma_deactivate_connection (pixma_t *);
+
+
+/** Enable or disable background tasks. Currently, the only one task
+ * is submitting interrupt URB in background.
+ * \param[in] enabled if not zero, enable background task.
+ * \see pixma_set_interrupt_mode() */
+int pixma_enable_background (pixma_t *, int enabled);
+
+/** Read the current device status.
+ * \param[out] status the current device status
+ * \return 0 if succeeded. Otherwise, failed.
+ */
+int pixma_get_device_status (pixma_t *, pixma_device_status_t * status);
+
+const char *pixma_get_string (pixma_t *, pixma_string_index_t);
+const pixma_config_t *pixma_get_config (pixma_t *);
+void pixma_fill_gamma_table (double gamma, uint8_t * table, unsigned n);
+const char *pixma_strerror (int error);
+
+/** @} end of API group */
+
+#endif