harvey/sys/lib/ghostscript/gs_img.ps

% (C) 2002 Artifex, Inc.  All rights reserved.
% 
% This software is provided AS-IS with no warranty, either express or
% implied.
% 
% This software is distributed under license and may not be copied,
% modified or distributed except as expressly authorized under the terms
% of the license contained in the file LICENSE in this distribution.
% 
% For more information about licensing, please refer to
% http://www.ghostscript.com/licensing/. For information on
% commercial licensing, go to http://www.artifex.com/licensing/ or
% contact Artifex Software, Inc., 101 Lucas Valley Road #110,
% San Rafael, CA  94903, U.S.A., +1(415)492-9861.

% $Id: gs_img.ps,v 1.3 2002/10/08 00:49:48 dan Exp $
% image, colorimage, and imagemask implementation

%
% The design of the overprint facility in Ghostscript requires that color
% specifications include the color space from which they were expressed,
% even after conversion to the device color model. Directly including this
% information in color specifications is usually not efficient, and is
% difficult to integrate into the existing code structure. The alternative
% approach taken is to extend a state mechanism through the device
% interface, and make the current color space, or more specifically,
% certain information about the current color space, a property of this
% state.
%
% For such a mechanism to work, it is necessary to identify all changes
% to the current color space. This is accomplished in the graphic library
% by funneling all changes to the current color space through the
% gs_setcolorspace procedure. At the PostScript interpreter level, this
% result is achieved by forcing color space changes through the
% setcolorspace operator.
%
% Aside from explicit use of setcolorspace, PostScript provides a few
% implicit methods of changing the current color space. The setgray,
% setrgbcolor, and setcmykcolor operators implicitly set the color space
% while explicitly setting the current color. Similarly, the colorimage
% operator and the traditional form of the image operator (5 operands)
% both temporarily modify the current color space while an image is
% being processed. The current file is concerned with the implementation
% of these two operators. In addition, the traditional form of the
% imagemask operator (5 operands), while it does not affect the current
% color space, is closely related to the image operator and thus is
% implemented in this file as well.
%
% In this implementation, all sampled objects are passed through one of
% the internal operators .image1, .imagemask1, .image1alpha, .image2,
% .image3, or .image4, each of which handles a specific ImageType value.
%
% The procedures in this file are responsible for constructing
% image dictionaries from a set of stack entries. This is, in principle,
% a trivial exercise. In practice it appears to be far more complex,
% primarily due to the need to reconstruct the original state in the
% event of an error. This is a particular problem for operators such as
% image, which include data source objects that may, directly or
% indirectly, be procedures. When these procedures are executed, the
% image operator's operands must have been cleared from the operand
% stack. Hence, the operand stack cannot be used to store state
% information. Similarly, the dictionary stack also cannot be used to
% store state information, as the data source procedures may depend on
% a particular dictionary being on the top of this stack.
%
% Adobe's PostScript implementations determine the extent to which the
% interpreter state is restored in the event of an error by the point at
% which the error is detected. Errors in the image/colorimage/imagemask
% operators that are detected before the data source procedures are
% executed restore the state in effect before the image was processed.
% Those that are detected as part of running the data source procedures
% only attempt to restore the state to that in effect at the start of
% the operator that failed (or at the conclusion of the data source
% procedure, if this procedure failed to push a string).
%
% The implementation given here follows the Adobe convention. The
% mechanism used is as follows:
%
%   1. Check that the stack has a sufficient number of operands, and
%      that enough of them have the proper type to allow construction
%      of the image dictionary. Any errors at this point are handled
%      in the conventional manner.
%
%   2. Build the image dictionary, in the process clearing the image/
%      colorimage/imagemask operands from the stack. No errors can
%      occur during this process.
%
%      (Special precautions could be taken during this step to handle
%      a limitcheck or VMError during the building of the image
%      dictionary, but this essentially never occurs in practice and, if
%      it did, is very unlikely to leave a useable state. Hence, we don't
%      bother with this possibility.)
%
%   3. The .image operator is executed in a stopped context. If it
%      returns abnormally, a check is made to see if the uppermost
%      operand on the stack is a color image dictionary. If so, the
%      original stack is created anew using this dictionary. (Because
%      the image operand works via colorimage, some additional special
%      handling is required in this case.)
%


%
% Create a dictionary of operators for specific image and image mask types.
% Each of these will always handle ImageType 1. Additional types are added
% as they are supported in specific interpreter levels or versions.
%
% These dictionaries are in systemdict for historical reasons.
%
.currentglobal true .setglobal
systemdict begin
/.imagetypes
  5 dict
  dup 1 /.image1 load put
def
/.imagemasktypes
  5 dict
  dup 1 /.imagemask1 load put
def
end
.setglobal

% 
% Build a dictionary of utility procedures and constants for use in
% impelementing the image operators. This dictionary is in global VM but
% is maintained (during initialization) in userdict. It should be pushed
% onto the dictionary stack when constructing image-related procedures
% and pseudo-operators.
%
% This dictionary is removed from userdict when initialization is
% completed.
%
.currentglobal true .setglobal
userdict /img_utils_dict 30 dict put
img_utils_dict begin


%
% Some useful local data structures:
%
%   img_csary maps the number of components in an image to the implied
%       color space.
%
%   img_decary is a prototype Decode array; subintervals of this array
%       may be used for fewer than 4 color components.
%
%   img_params_ary is a list of the parameters to be built in the image
%       dictionary for a colorimage invocation. ImageType is given a
%       fixed value; the other parameters are in stack order (IMG_NComps
%       is the number of components).
%
%   img_mask_params_ary is the equivalent of img_params_ary for imagemask
%       invocations. Polarity is a proxy for Decode, and is replaced
%       by the Decode key in the image dictionary.
%
%   img_mask_check_ary is the set of parameters that must be present in
%       an image dictionary generated by an imagemask invocation. This
%       differs from img_mask_params_ary in that Decode replaces Polarity.
%
/img_csary [ null /DeviceGray null /DeviceRGB /DeviceCMYK ] def
/img_decary [ 0 1  0 1  0 1  0 1 ] def

/img_params_ary
  [
    /ImageType  /IMG_NComps  /MultipleDataSources  /DataSource
    /ImageMatrix  /BitsPerComponent  /Height  /Width   /Decode
  ]
def
/img_check_ary //img_params_ary def
/img_unbuild_ary
 //img_params_ary 1 1 index length 2 sub getinterval
def

/img_mask_params_ary
  [ /ImageType  /DataSource  /ImageMatrix  /Polarity  /Height  /Width ]
def
/img_mask_check_ary
  [
    /ImageType  /BitsPerComponent
    /DataSource  /ImageMatrix  /Decode  /Height  /Width
  ]
def
/img_mask_unbuild_ary
 //img_mask_check_ary 2 1 index length 2 sub getinterval
def


%
%   <?any?>  <array>   img_check_keys   <?any?>  <bool>
%
% Verify that:
%   that there are at least two entries on the stack, and
%   the second (lower) entry is a dictionary, and
%   that dictionary contains all of the keys in the array
%
% If any one of these conditions does not hold, pop the array and push
% false; otherwise pop the array and push true. This utility is used by
% the colorimage and imagematrix procedures to determine if .image left
% the image dictionary on the stack after an abnormal return.
%
/img_check_keys
  {
    count 2 ge
      {
        1 index type /dicttype eq
          {
            true exch
              {
                2 index exch known and
                dup not
                  { exit }
                if
              }
            forall
          }
          { pop //false }
        ifelse
      }
      { pop //false }
    ifelse
  }
.bind def

%
% Procedures to convert a set of stack entries to a dictionary. There is
% a procedure associated with each key, though most keys use the same
% procedure. The dictionary to be built is at the top of the dictionary
% stack. Stack handling for the procedures is:
%
%   <?val0?> ... <?val(n - 1)?>  <key>   proc   -
%
% Parameters are handle in inverse-stack order, so inter-parameter
% dependencies that on the stack can generally be used here.
%
/img_params_dict
  mark
    /ImageType { 1 def } .bind

    /IMG_NComps { exch def } .bind      % number of components
    /MultipleDataSources 1 index
    /Width 1 index
    /Height 1 index
    /ImageMatrix 1 index
    /BitsPerComponent 1 index
    /DataSource 1 index

    % Polarity is a proxy for Decode; it never appears in a dictionary
    /Polarity
      {
        pop
          { { 1 0 } }
          { { 0 1 } }
        ifelse
        /Decode exch cvlit def
      }
    .bind

    % the definition of Decode is based on the number of components
    /Decode { //img_decary 0 IMG_NComps 2 mul getinterval def } .bind
  .dicttomark
def

%
%    <oper_0>  ...  <oper_n>  <array>   img_build_dict   <dict>
%
% Build a dictionary. This will always be done in local VM. The array is
% a list of the keys to be associated with operands on the stack, in
% inverse stack order (topmost element first). The caller should verify
% that the dictionary can be built successfully (except for a possible
% VMerror) before calling this routine.
%
/img_build_dict
  {
    % build the dictionary in local VM; all for 2 extra entries
    .currentglobal false .setglobal
    1 index length 2 add dict
    exch .setglobal
    begin

    % process all keys in the array
      { //img_params_dict 1 index get exec }
    forall

    % if BitsPerComponent is not yet defined, define it to be 1
    currentdict /BitsPerComponent known not
      { /BitsPerComponent 1 def }
    if

    currentdict end
  }
.bind def

%
%   <dict>  <array>   img_unbuild_dict   <oper_0>  ...  <oper_n>
%
% "Unbuild" a dictionary: spread the contents the dictionary back onto the
% stack, in the inverse of the order indicated in the array (inverse is
% used as this order is more convenient for img_build_dict, which is
% expected to be invoked far more frequently).
%
/img_unbuild_dict
  {
    exch begin
    dup length 1 sub -1 0
      { 1 index exch get load exch }
    for
    pop
    end
  }
.bind def


%
%   <width>  <height>  <bits/component>  <matrix>  <dsrc0> ...
%   <multi>  <ncomp>  <has_alpha>
%   img_build_image_dict
%   <dict>  <has_alpha>
%
% Build the dictionary corresponding to a colorimage operand stack. This
% routine will check just enough of the stack to verify that the
% dictionary can be built, and will generate the appropriate error if this
% is not the case.
%
% The <has_alpha> boolean is used to support the Next alphaimage extension.
%
% At the first level, errors in this procedure are reported as colorimage
% errors. The error actually reported will usually be determined by the
% pseudo-operator which invokes this routine.
%
/img_build_image_dict
  {
    % Veify that at least 8 operands are available, and that the top three
    % operands have the expected types
    count 8 lt
      { /.colorimage cvx /stackunderflow signalerror }
    if
    3 copy
    type /booleantype ne exch
    type /integertype ne or exch
    type /booleantype ne or
      { /.colorimage cvx /typecheck signalerror }
    if

    % verify that the number of components is 1, 3, or 4
    1 index 1 lt 2 index 2 eq or 2 index 4 gt or
      { /.colorimage cvx /rangecheck signalerror }
    if

    % Verify that the required number of operands are present if multiple
    % data sources are being used. If this test is successful, convert
    % the data sources to an array (in local VM).
    2 index
      {
        % if an alpha component is present, this adds one more component
        2 copy
          { 1 add }
        if
        dup count 9 sub gt
          { /.colorimage cvx /stackunderflow signalerror }
        if

        % build the DataSource array in local VM
        dup .currentglobal false .setglobal exch array exch .setglobal

        % stack: <w> <h> <bps> <mtx> <d0> ... <multi> <n> <alpha> <n'> <array>
        5 1 roll 4 add 3 roll astore 4 1 roll
      }
    if

    % the image dictionary can be built; do so
    % stack: <w> <h> <bps> <mtx> <dsrc|dsrc_array> <multi> <n> <alpha>
    8 1 roll //img_params_ary //img_build_dict exec exch
  }
.bind def

%
%   <?dict?>
%   img_unbuild_image_dict
%   <width>  <height>  <bits/component>  <matrix>  <dsrc0> ...
%   <multi>  <ncomp>
%
% If the top entry of the stack is a dictionary that has the keys required
% by a colorimage dictionary, unpack that dictionary onto the stack.
% Otherwise just leave things as they are. Note that the <has_alpha>
% parameter is not pushd onto the stack.
%
/img_unbuild_image_dict
  {
    //img_check_ary //img_check_keys exec
      {
        //img_unbuild_ary //img_unbuild_dict exec
        1 index type /booleantype eq
          {
            1 index
              { 3 1 roll aload length 2 add -2 roll }
            if
          }
        if
      }
    if
  }
.bind def


%
%   <width>  <height>  <polarity>  <matrix>  <dsrc>
%   img_unbuild_imagemask_dict
%   <dict>
%
% Build the dictionary corresponding to an imagemask stack. This routine
% will verify that the appropriate number of operands are on the stack,
% and that polarity is a boolean. This is all that is necessary to build
% the dictionary.
%
/img_build_imagemask_dict
  {
    % check for proper number of operands
    count 5 lt
      { /imagemask load /stackunderflow signalerror }
    if

    % verify that polarity is a boolean
    2 index type /booleantype ne
      { /imagemask load /typecheck signalerror }
    if

    % the imagemask dictionary can be built; do so
    //img_mask_params_ary //img_build_dict exec
  }
.bind def

%
%   <?dict?>
%   img_unbuild_imagemask_dict
%   <width>  <height>  <polarity>  <matrix>  <dsrc>
%
% If the top entry of the stack is a dictionary that has the keys rquired
% by an imagemask dictionary, unpack that dictionary onto the stack.
% Otherwise just leave things as they are.
%
/img_unbuild_imagemask_dict
  {
    //img_mask_check_ary //img_check_keys exec
      {
        //img_mask_unbuild_ary //img_unbuild_dict exec
        3 -1 roll
        dup type dup /arraytype eq exch /packedarraytype eq or
        1 index rcheck and
          { 0 get 1 eq }
        if
        3 1 roll
      }
    if
  }
.bind def


%
%   <width>  <height>  <bits/component>  <matrix>  <dsrc_0> ...
%   <multi>  <ncomp>  <has_alpha>
%   .colorimage 
%   -
%
% Convert the image/colorimage operator from their traditional form to
% the dictionary form. The <has_alpha> operand is used ot support the
% Next alphaimage extension.
%
% Error handling for these operators is a bit complex, due to the stack
% handling required of operators that potentially invoke procedures.
% This problem is discussed in the comment above. The facts relevant to
% this particular implementation are:
%
%   1. The .image1 (or .alphaimage) operator is executed in a stopped
%      context, so that we can undo the gsave context in the event of
%      an error.
%
%   2. In the event of an error, the stack is examined to see if the
%      dictionary passed to .image1 (.alphaimage) is still present.
%      If so, this dictionary is "unpacked" onto the stack to re-
%      create the original stack. The <has_alpha> parameter is not
%      pushed onto the stack, as it is not required for any of the
%      pseudo-operators than invoke this procedure.
%
%   3. The use of pseudo-operators in this case may yield incorrect
%      results for late-detected errors, as the stack depth will be
%      restored (even though the stack is not). This is, however, no
%      worse than the prior (level >= 2) code, so it should cause no
%      new problems.
%
/.colorimage
  {
    % build the image dictionary
    //img_build_image_dict exec

    % execute .image1 in a stopped context
      {
        gsave
        0 .setoverprintmode             % disable overprint mode for images
        //img_csary 2 index /IMG_NComps get get setcolorspace
          { .alphaimage }
          { .image1 }
        ifelse
      }
    stopped
    grestore
      {
        //img_unbuild_image_dict exec
        /.colorimage cvx $error /errorname get
        signalerror
      }
    if
  }
.bind def


% 
%   <width>  <height>  <bits/component>  <matrix>  <dsrc_0> ...
%   <multi>  <ncomp>
%   colorimage 
%   -
%
% Build the colorimage pseudo-operator only if setcolorscreen is visible.
%
systemdict /setcolorscreen .knownget
  {
    type /operatortype eq
      {
        /colorimage 
          {
             //false
               //.colorimage
             stopped
               { /colorimage load  $error /errorname get signalerror }
             if
          }
        .bind systemdict begin odef end
      }
    if
  }
if


%
%   width  height  bits_per_component  matrix  data_src   image   -
%   
%   <dict>   image   -
%
% Some special handling is required for ImageType 2 (Display PostScript
% pixmap images) so as to set the appropriate color space as the current
% color space.
%
/image
  {
    dup type /dicttype eq languagelevel 2 ge and
      { 
        dup /ImageType get dup 2 eq
          {
            % verify the ImageType 2 is supported
            //.imagetypes exch known
              {
                %
                % Set either DevicePixel or DeviceRGB as the current
                % color space. DevicePixel is used if the image data is
                % to be copied directly, with only a geometric
                % transformation (PixelCopy true). The use of DeviceRGB
                % in the alternate case is not, in general, correct, and
                % reflects a current implementation limitation. Ideally,
                % an intermediate color space should be used only if
                % the source and destination color models vary; otherwise
                % the native color space corresponding to the color model
                % should be used.
                %
                % The mechanism to determine depth for the DevicePixel
                % color space when BitsPerPixel is not available is 
                % somewhat of a hack.
                %
                gsave
                0 .setoverprintmode     % disable overprintmode for images
                dup /PixelCopy .knownget dup
                  { pop }
                if
                  {
                      [
                        /DevicePixel
                        currentpagedevice dup /BitsPerPixel .knownget
                          { exch pop }
                          {
                            /GrayValues .knownget not
                              { 2 }     % try a guess
                            if
                            ln 2 ln div round cvi
                          }
                        ifelse
                      ]
                  }
                  { /DeviceRGB }
                ifelse
                setcolorspace
                //.imagetypes 2 get
                stopped
                grestore
                  { /image load $error /errorname get signalerror }
                if
              }
              { /image load /undefined signalerror }
            ifelse
          }
          {
            gsave
            0 .setoverprintmode         % disable overprintmode for images
            //.imagetypes exch get
            stopped
            grestore
              { /image load $error /errorname get signalerror }
            if
          }
        ifelse
      }
      { 
        //false 1 //false
          //.colorimage
        stopped
          { /image load $error /errorname get signalerror }
        if
      }
    ifelse
  }
.bind systemdict begin odef end


%
%   width  height  polarity  matrix  datasrc   imagemask   -
%
% See the comment preceding the definition of .colorimage for information
% as to the handling of error conditions.
%
/imagemask
  {
    dup type /dicttype eq languagelevel 2 ge and
      { dup /ImageType get //.imagemasktypes exch get exec }
      {
        //img_build_imagemask_dict exec
          { .imagemask1 }
        stopped
          {
            //img_unbuild_imagemask_dict exec
            /imagemask load $error /errorname get signalerror
          }
        if
      }
    ifelse
  }
.bind systemdict begin odef end

end        % img_utils_dict
.setglobal  % restore VM mode