gdeveprn.h

openmeetings组件之GS openmeetings组件之GS openmeetings组件之GS

/******************************************************************************
  File:     $Id: gdeveprn.h,v 1.23 2001/04/30 05:15:51 Martin Rel $
  Contents: Header file for the abstract ghostscript device 'eprn'
  Author:   Martin Lottermoser, Greifswaldstrasse 28, 38124 Braunschweig,
            Germany; e-mail: [e-mail].

*******************************************************************************
*									      *
*	Copyright (C) 2000, 2001 by Martin Lottermoser			      *
*	All rights reserved						      *
*									      *
*******************************************************************************

  The 'eprn' device
  *****************
  In developing my hpdj/pcl3 driver for PCL 3+ I had to implement a lot of
  functionality which was logically independent of PCL. This indicated that the
  functionality offered by ghostscript's 'prn' device was insufficient and
  should be extended, leading to this "extended prn device".


  Functionality
  =============
  The "eprn" device offers the following services to derived devices:
  - A simple but still flexible rendering model. A derived device defines
    printer capability descriptions listing the supported rendering parameters,
    lets the eprn device handle the user's rendering requests, and then just
    fetches the pixels.
  - A PostScript-conforming initialization of default user space with respect
    to landscape orientation and support for the standard page device parameter
    "LeadingEdge".
  - Recognition of media sizes from the document and checking of supported
    sizes based on printer descriptions
  - Flexible handling of size-specific hardware margins
  - Counting of pages printed across gs invocations by means of page count
    files


  Rendering Model
  ===============
  The "eprn" device parameterizes the printer's rendering capabilities as
  follows:
  - process colour model (Gray, RGB, CMY, CMY+K, CMYK)
  - resolution in horizontal and vertical directions
  - number of intensity levels per colorant, chosen independently for black
    and non-black (RGB or CMY) colorants.
  In addition, the rendering process as implemented in this driver is
  parameterized by:
  - method for rendering intensities (printer, halftones or error diffusion)
  These parameters are specified by the user. The device checks whether the
  printer supports the requested combination and, if it does, sets
  ghostscript's internal data structures accordingly.

  The derived device can obtain the resulting pixels by successively calling
  eprn_get_planes() from the page printing procedure.


  Device Coordinates
  ==================
  "Pixmap device space" is the coordinate system used by the "prn" device for
  generating a pixmap and implicit in the API for accessing it (e.g.,
  gdev_prn_copy_scan_lines()). In identifying the directions "left", "bottom",
  "right" and "top" I'm assuming that the x axis is pointing to the right and
  the y axis downwards. This is not concerned with the orientation of device
  space on a sheet printed but is merely a definition of what, e.g., "down"
  means for the eprn device: it is defined as "towards increasing prn y values".
  This makes the code more readable for the case where the real device
  coordinate system (on the sheet) has just this orientation. Too bad for the
  others :-).

  Terms like "width" and "height" are also defined with respect to this
  interpretation, i.e., "width" is an extension in x direction.

  Note that names and interpretations of some of ghostscript's standard
  device structure fields (like 'width', 'height') are also based on this
  convention although this is not explicitly stated. This does however not
  apply to all parameters: for example, HWMargins[] and MediaSize[] are to be
  interpreted in default user space (see gx_default_clip_box()).

  One key assumption of the eprn device is that the top edge of pixmap device
  space is the edge closest to and parallel with the medium's leading edge.
  It is the responsibility of the derived device to ensure this. Usually
  it means that raster lines have to be printed in the order of ascending y.
  (The eprn device will work if the derived device violates this condition, but
  the meaning of user-visible properties of the device would change.)

  The device sets up the device coordinate system such that the device space
  origin is the top left corner of the imageable area where "top" and "left"
  refer to you holding the sheet with the printed side towards you and the
  leading edge at the top. Units and directions are identical with pixmap
  device space.


  Page Descriptions
  =================
  When a PostScript document requests a particular page size by specifying its
  width and height in default user space the eprn device combines this
  information with certain conditions imposed by the derived device and looks
  for a matching page description entry in the printer's capability
  description. The following information from such an entry is needed for
  correctly setting up the relation between default user space and device space:

    - default orientation of the sheet in pixmap device space
      (MS_TRANSVERSE_FLAG; set iff the sheet has width > height in pixmap
      device space)
    - hardware margins

  This part is interpreted by the eprn device.

  In addition, a page description entry may contain a number of flags
  indicating special conditions under which this entry is to be selected or
  carrying information on how to configure the printer. The flags are those
  defined by mediasize.h (except that MS_TRANSVERSE_FLAG and MS_ROTATED_FLAG
  may not be used for this purpose), their interpretation is up to the derived
  device which must request them or to which they will become visible when the
  entry is selected.

  The eprn device takes the following items as the request to be matched with a
  page description entry in the printer's capability description:

    - the media size of the document and, if set, the "LeadingEdge" page device
      parameter
    - a pattern of desired (not necessarily *required*) flags
    - an ordered list of optional flags

  Media size and LeadingEdge are set via PostScript or the command line, the
  flags can be set by the derived device through its device structure instance
  or by calling eprn_set_media_flags(). The optional flags when combined with
  the bitwise OR effectively define a mask of bits which may be ignored when
  checking whether an entry matches the desired flags. The order of optional
  flags is from most to least desirable to ignore.

  The complete request is compared to the list of page descriptions as follows:

   1. If the media size, irrespective of flags, cannot be matched at 5 bp
      tolerance, the request fails with an error message to standard error.
   2. Otherwise a shortened list containing all entries having a matching
      size is compiled, at least conceptually. If the device supports custom
      page sizes, they are listed at the end. This is the "base list".
   3. If LeadingEdge is not null, the MS_TRANSVERSE_FLAG is set or cleared
      accordingly in the pattern of desired flags. This flag is also always
      added to the front of the list of optional flags.
   4. A mask of flags to be ignored is set to zero.
   5. The base list is searched for an entry agreeing with the desired flags
      except possibly for those in the ignore mask.
   6. If no such entry is found, the next flag in the list of optional flags is
      added to the ignore mask and execution continues with step 5. If there is
      no such flag, the request fails and the flag mismatch reporting function
      is called (see below).
   7. If a matching entry is found the list of optional flags is processed
      backwards starting with the flag before the last one added to the ignore
      mask. For each such flag an attempt is made to remove it from the mask.
      If there still is at least one matching entry in the base list the flag
      remains cleared, otherwise it is put back into the mask.
   8. Finally, the first entry matching the request mask and the current
      ignore mask will be selected:
      - its media code will be made available to the derived device in the
        eprn device's 'code' field,
      - the hardware margins will be set from the page description (unless the
	user has explicitly specified a value for the ".HWMargins" page device
	parameter),
      - default user space will be configured based on sheet orientation
	(transverse or not in device space) and page orientation (portrait or
	landscape in default user space).

  Because the error message in step 6 has to report a mismatch on the flags
  and because the interpretation of the flags is fixed by the derived device,
  an error message issued by the eprn device may not be particularly
  illuminating to the user (the user will usually think in terms of the
  interpretation the derived device associates with these flags). Therefore
  issuing this error message can be delegated to a function ("flag mismatch
  reporting function") specified by the derived device in its device structure
  instance.

******************************************************************************/

#ifndef _gdeveprn_h	/* Inclusion protection */
#define _gdeveprn_h

/* Configuration management identification */
#pragma ident "@(#)$Id: gdeveprn.h,v 1.23 2001/04/30 05:15:51 Martin Rel $"

/*****************************************************************************/

/* Special Aladdin header, must be included before <sys/types.h> on some
   platforms (e.g., FreeBSD). This necessity seems to be triggered for example
   by <stdio.h>. */
#include "std.h"

/* Standard headers */
#include <stdio.h>	/* for 'FILE' and 'size_t' */

/* Ghostscript headers */
#include "gdevprn.h"
/* This header is assumed to include a definition for 'bool' (stdpre.h). */

/* Other header files */
#include "mediasize.h"

/*****************************************************************************/

/*  Types to describe supported page sizes and associated setup information.
    All sizes are in bp and all orientations refer to pixmap device space.
 */

/* Discrete page sizes */
typedef struct {
  ms_MediaCode code;
   /* The media flags in 'code' identify the conditions under which the size
      is supported ("required flags") and carry information needed in order
      to adapt ghostscript or the printer to using this entry ("optional
      flags"). The distinction between the two groups of flags is fixed by the
      derived device when calling eprn_set_media_flags() except that special
      rules apply to MS_TRANSVERSE_FLAG which is handled by eprn.
      Setting MS_TRANSVERSE_FLAG indicates that media of this size are normally
      fed such that width > height in pixmap device space, otherwise
      width <= height is assumed.
      Setting MS_ROTATED_FLAG is not permitted.
      The interpretation of all other flags is up to the derived device.
    */
  float left, bottom, right, top;
   /* Hardware margins (non-negative) in bp */
} eprn_PageDescription;


/* Custom page sizes */
typedef struct {
  /*  The first two lines have the same meaning as for 'eprn_PageDescription'.
      However, apart from flags, the 'code' field must be 'ms_CustomPageSize'.
  */
  ms_MediaCode code;
  float left, bottom, right, top;
  float width_min, width_max, height_min, height_max;
   /* Permissible range in bp for width and height when a sheet's dimension is
      given such that width <= height. */
} eprn_CustomPageDescription;

/*
  Here follows an example of using "eprn_PageDescription". It describes a
  printer supporting A4 and US Letter, the first with 5 mm margins, the latter
  with 0.2 inches:

    const eprn_PageDescription page_description[] = {
	{ms_A4,       5*BP_PER_MM,   5*BP_PER_MM,   5*BP_PER_MM,   5*BP_PER_MM},
	{ms_Letter, 0.2*BP_PER_IN, 0.2*BP_PER_IN, 0.2*BP_PER_IN, 0.2*BP_PER_IN},
	{ms_none, 0, 0, 0, 0}
      };

  The last entry is a sentinel value which will be required later.

******************************************************************************/

/*  Types to describe supported combinations of resolutions, process colour
    models and intensity levels per colorant

    These types often contain pointers to lists terminated with a sentinel
    value. As these are usually static data, this makes it easier to share data
    between printer descriptions.
 */

/* Process colour models */
typedef enum {
  eprn_DeviceGray,
  eprn_DeviceRGB,
  eprn_DeviceCMY,
  eprn_DeviceCMY_plus_K,
   /* 'eprn_DeviceCMY_plus_K' is a process colour model using the CMYK
      colorants but never mixing black with one of the others. The underlying
      native colour space is 'DeviceRGB'. */
  eprn_DeviceCMYK
} eprn_ColourModel;

/* Horizontal and vertical resolutions w.r.t. pixmap device space */
typedef struct {
  float h, v;
} eprn_Resolution;