notes.tex

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

  \item The \prog{static\_procs} variable points to a static table of
    type \prog{gx\_device\_procs} containing pointers to functions.
    It is common to all device instances of the same type.
  \item \prog{page\_procs} is of type \prog{gx\_page\_device\_procs}.
    This is a table of pointers to functions peculiar to page devices.
  \item The \d{device procedure table} \prog{procs} is also of
    type \prog{gx\_device\_procs}
    (but not a pointer to that type as \prog{static\_procs} is).
    The entries in this table (or the functions pointed to) are the
    \d{device procedures}.
\end{itemize}

The function \prog{gx\_device\_set\_procs()} checks whether
\prog{static\_procs} is \prog{NULL} or not.	% gsdevice.c
If it is not,
the table pointed to is copied over \prog{procs} and
\prog{static\_procs} is set to \prog{NULL}.

More important, however, is that almost all \prog{NULL} entries in the
device procedure table are overwritten with default values.
This is done by \prog{gx\_device\_fill\_in\_procs()}.
It first calls \prog{gx\_device\_set\_procs()}
and then replaces null entries for all device procedures except
\prog{fill\_rectangle}~[gs~5.50].\footnote{
  The entries for \prog{image\_data} and \prog{end\_image} are always
  overwritten with non-null default values
  even if they are non-null to begin with.}

The list of device procedures is frequently growing.
In \gs\ version~5.50 this table has 43~entries.
Check the definition of \prog{gx\_device\_proc\_struct()} in \file{gxdevcli.h}
for the current list.

A device procedure should be called by using the \prog{dev\_proc()} macro:
it takes a pointer to a device instance and the name of a device
procedure table field as arguments and is expanded into the entry in the
device procedure table.

While entries in \prog{*static\_procs} may not change,
the device procedures in \prog{procs} can change during a device's lifetime.
The macro \prog{set\_dev\_proc()} is intended for this purpose.
%???
%The \textit{prn\/} device, for example,
%sets a number of device procedures for rendering when the device is opened
%(\prog{gdev\_prn_\allocate()}) and restores the old values when the device is
%closed (\prog{gdev\_prn\_tear\_down()}).

%==============================================================================

\subsection{\Gs\ Devices in PostScript}

\subsubsection{Type, \Gs\ Initialization and State}

\Gs\ introduces a new basic type \ps{devicetype} for representing ghostscript
device (structure) instances.
Instances of this type are composite objects.	% See 'ref_type' in iref.h.

% See gs_init.ps.
On initialization,
\gs\ repeatedly executes the \ps{.getdevice} operator to obtain
all known device structure instances.
It then creates a dictionary \ps{devicedict} in \ps{systemdict} containing
for each device an array of length~2;
the first entry is the device structure instance,   % from 'gx_device_list[]'
the second is \ps{null}\footnote{
  Actually, the PostScript initialization code sets the second entry to be
  \ps{null} if the device is not writable and
  makes it a copy of the first if it is.
  However, the implementation of \ps{.getdevice} (\prog{zgetdevice()})
  always returns a read-only object~[gs~5.50].	% See zdevice.c.
  % Also tested with gs 5.50 and gs 5.10 binaries.
  }.
Entries in \ps{devicedict} have the string returned by \ps{.devicename} as a
key (\prog{dname} field in the device structure).	% See zdevice.c.

The device instance current in the graphics state
can be obtained with the operator
\ps{currentdevice} implemented in \prog{zcurrentdevice()}.

%------------------------------------------------------------------------------

\subsubsection{Switching Devices}

The procedure \ps{selectdevice} calls first \ps{finddevice} and then
\ps{setdevice}.	% Actually, it also calls \ps{.setdefaultscreen}.

The procedure \ps{finddevice} looks into \ps{devicedict} to find a device by
its name and checks the second entry in the array.
If it is \ps{null},
the entry is replaced by the result of \ps{copydevice} applied to the first
entry.
In all cases, this second entry is returned.

\ifdraft
??? TEST: What happens on multiple selection?
\fi

\ps{copydevice} is a \gs\ operator implemented in \prog{zcopydevice()}.
% See zdevice.c.
The latter calls \prog{gs\_copydevice()}	% gsdevice.c
which allocates storage for a new device instance,
calls \prog{gx\_device\_init()} and sets the device variable \prog{is\_open}
to \prog{false}.
The function \prog{gx\_device\_init()} copies the source device instance
storage into the new instance with the exception of the \prog{memory} variable.

The procedure \ps{setdevice} calls the operator \ps{.setdevice} implemented
in \prog{zsetdevice()}.	% zdevice.c
This function calls \prog{gs\_setdevice\_no\_erase()} and clears the
underlying page device.	% macro clear_pagedevice()

\ifdraft
??? What happens with the old device?
\fi

The function \prog{gs\_setdevice\_no\_erase()} first checks whether the device
is already open.
If not, it calls \prog{gx\_device\_fill\_in\_procs()} and the
\prog{open\_device} device procedure and finally it sets \prog{is\_open = true}.
Then it calls \prog{gs\_setdevice\_no\_init()}, \prog{gs\_initmatrix()} and
\prog{gs\_initclip()}.

\prog{gs\_setdevice\_no\_init()} sets the colour mapping procedures
in the graphics state from the device's colour mapping procedures
(calling \prog{gx\_set\_cmap\_procs()}).

%******************************************************************************

\section{\Gs\ Device Parameters}

The variables in a device instance determine the values of its
\d{device parameters}.
These parameters are a subset of the
page device parameters of the corresponding PostScript output device.
The connection between the two and the way in which the device parameters may
be accessed is an area where \gs's documentation is particularly reticent.

%==============================================================================

\subsection{Parameter Dictionaries}

A device parameter is identified by a string, its name.
If a device supports a particular parameter,
it associates a typed value with this name.
\Gs\ has an internal API for dealing with collections of such name-value pairs.

%------------------------------------------------------------------------------

\subsubsection{Types for Parameters}

The name of a parameter is of type \prog{gs\_param\_name}
which is defined as \prog{const char~*}.

Each parameter has a type associated with it which is stored in an instance
of type \prog{gs\_param\_type}:
\begin{program}	% gsparam.h
typedef enum \lb
\    /* Scalar */
\    gs_param_type_null, gs_param_type_bool, gs_param_type_int,
\    gs_param_type_long, gs_param_type_float,
\    /* Homogenous collection */
\    gs_param_type_string, gs_param_type_name,
\    gs_param_type_int_array, gs_param_type_float_array,
\    gs_param_type_string_array, gs_param_type_name_array,
\    /* Heterogenous collection */
\    gs_param_type_dict, gs_param_type_dict_int_keys, gs_param_type_array
\rb\ gs_param_type;
\end{program}
In addition, there is a macro \prog{gs\_param\_type\_any} which resolves to
an expression of this type and which can be used to denote any type.

\ifdraft
???
What is the concept of ``type'' here? PostScript, C, a mixture of both?
Add description of collections.
\fi

The type \prog{gs\_param\_value} is used to store values of parameters.
It is a \prog{union} of the following C~types:
\begin{quote}
  \prog{bool}, \prog{int}, \prog{long}, \prog{float},
  \prog{gs\_param\_string},		% twice
  \prog{gs\_param\_int\_array}, \prog{gs\_param\_float\_array},
  \prog{gs\_param\_string\_array},	% twice
  \prog{gs\_param\_collection}
\end{quote}

Finally, the type \prog{gs\_param\_typed\_value} combines a type description
with a value:
\begin{program}	% gsparam.h
  typedef struct gs_param_typed_value_s \lb
  \    gs_param_value value;
  \    gs_param_type type;
  \rb\ gs_param_typed_value;
\end{program}

%------------------------------------------------------------------------------

\subsubsection{Type and Operations for Parameter Collections}

A \d{parameter dictionary} represents an unordered collection of
instances of type \prog{gs\_param\_typed\_value}
and is of the C~type \prog{gs\_param\_list}
% (also known as \prog{struct gs\_param\_list\_s})
or of a type having the same initial storage layout as this type.
This is the same convention as used to simulate type inheritance for
device structures:
\prog{gs\_param\_list} should be
considered as an abstract base class defining access routines for
parameter dictionaries
while its derived types provide implementations for the routines and storage
for the parameters.
This abstract interface is declared in \file{gsparam.h}.

Concrete implementations of this abstract interface are the following types:
\begin{quote}\begin{flushleft}
  \prog{gs\_c\_param\_list},	% gsparam.h
  \prog{dict\_param\_list},	% iparam.h
  \prog{array\_param\_list},	% iparam.h
  \prog{stack\_param\_list},	% iparam.h
  \prog{printer\_param\_list\_t}	% gdevpsdf.c
\end{flushleft}\end{quote}
The only one of interest to implementors of device drivers is
\prog{stack\_param\_list} because it is used to represent objects on the
operand stack.
\ifdraft
??? More about it later?
\fi

There exists a macro \prog{gs\_param\_list\_common} to obtain the list of
declarations common to all parameter dictionary types.
It resolves to:
\begin{program}
  const gs_param_list_procs *procs;
  gs_memory_t *memory;	% Actually, the semicolon is not part of the macro.
\end{program}
The \prog{procs} member points to a table of pointers to the
implementation's access methods.
This table contains the following members\footnote{
    I am not aware of any official description for the semantics or behaviour of
    these functions at the level of abstraction for \prog{gs\_param\_list};
    the comments in \file{gsparam.h} are insufficient for this purpose.
    These descriptions are therefore heavily based on the actual implementation
    for \prog{iparam\_list} which is an abstract type between
    \prog{gs\_param\_list} and a number of concrete implementations
    including \prog{stack\_param\_list}.
  }:
\begin{itemize}
  \item \prog{int (*xmit\_typed)(gs\_param\_list *, gs\_param\_name,
      gs\_param\_typed\_value *);}

    This routine is used to ``transmit'' a value.
    This means either to put a value into the dictionary (writing)
    or to extract it (reading).
    Which direction is chosen depends on the function pointed to,
    i.e., unless you modify this pointer you can either read or write the
    parameter dictionary but not both.

    A reading implementation of \prog{xmit\_typed} returns zero if the
    parameter value was successfully extracted,
    one if the parameter does not exist,
    and a negative value on error.
    A writing implementation returns zero or one on success and
    a negative value on error.

    The reading implementation of \prog{xmit\_typed} for
    \prog{stack\_param\_list}	% Actually, for 'iparam_list'.
    keeps track of which parameter was accessed and what the result was.
    % See comments in iparam.h and the 'results' field in 'iparam_list'
    % [gs 5.50].

    \ifdraft
    ??? Discuss selective writing.
    \fi
  \item \prog{int (*signal\_error)(gs\_param\_list *, gs\_param\_name, int);}

    This routine is used to associate an error code (the last argument) with
    the parameter designated.
    A parameter dictionary can for example store this code in the list together
    with the parameter's value.
    The function must \emph{never\/} be called for a
    non-existent parameter [gs~5.50].
    % Looking at iparam.c, this should give a core.

    This routine is in particular intended to be used by functions extracting
    values from a parameter dictionary and discovering that
    the type is incorrect or the value is outside the permissible range.
  \item \prog{int (*commit)(gs\_param\_list *);}

    This function is used to perform some final processing after extracting
    all interesting values from a parameter dictionary.
    It can for example check that all the parameters present have been
    extracted,
    i.e., that there are no unknown parameters left in the dictionary.
    % ref_param_read_commit() does this if it has been requested.
    % If there are undefined parameters, their 'result' codes are set to
    % 'e_undefined'.

    The routine returns zero on success and a negative value on error.
  \item \prog{int (*next\_key)(gs\_param\_list *, gs\_param\_enumerator\_t *,
    gs\_param\_key\_t *);}

    This routine is useful for debugging because it can be used to iterate over
    all entries in a parameter dictionary.
    The second argument points to an iterator which stores the last position
    accessed;
    it must have been initialized by calling