notes.tex

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

    \prog{void param\_init\_enumerator(gs\_param\_enumerator\_t *)} before
    the first call to this function.
    The third argument
    (the type is an alias for \prog{gs\_param\_string})	% gs 6.50
    will receive the name of the next parameter if there is
    one (return code is zero),
    otherwise the return code is~1 (no more parameters) or negative (error).
  \item In addition, there are the members
    \prog{begin\_xmit\_collection},
    \prog{end\_xmit\_collection},
    \prog{request},
    \prog{requested},
    and
    \prog{get\_policy}.
\end{itemize}

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

\subsubsection{Interface for Drivers}

The methods in parameter dictionaries are not particularly interesting
from the point of view of writing a driver,
but there are some functions on top of this interface which are.


\paragraph{Reading.}

For reading a value from a parameter dictionary, the basic routine is:
\begin{program}
int param_read_requested_typed(gs_param_list *, gs_param_name,
\  gs_param_typed_value *);
\end{program}
This function expects a requested type to have been filled into the
\prog{type} field of the entry pointed to be the third argument.
It calls the \prog{xmit\_typed} function.
If the latter returns a non-zero exit code, this code is returned.
Otherwise the function checks for a mismatch between the requested and
the actual type
and tries to convert between the two if necessary and possible.
For example, if the actual parameter is of type \prog{gs\_param\_type\_int}
its value can also be extracted as \prog{gs\_param\_type\_long}
or \prog{gs\_param\_type\_float}.	% See param_coerce_typed().
If the types do not match,
a value of \prog{gs\_error\_typecheck} is returned.
Otherwise the result is returned via the \prog{value} field in the
third argument.

There is a macro \prog{param\_read\_typed()} which effectively calls
\prog{param\_read\_requested\_typed()} with the value
\prog{gs\_param\_type\_any} and
can be used to fetch a parameter value irrespective of its type.
The \prog{type} field in the third argument will contain the actual type.

Implemented on top of \prog{param\_read\_requested\_typed()} there are several
functions \prog{param\_read\_\textit{type}()} which request and return a value
of a specific type.
For an \prog{int}, the routine is:
\begin{program}
int param_read_int(gs_param_list *, gs_param_name, int *);
\end{program}
These functions should be used in preference to the others.


\paragraph{Writing.}

For writing a parameter there is a macro \prog{param\_write\_typed()} which
should be called as if it were the following function:
\begin{program}
  int param_write_typed(gs_param_list *, gs_param_name,
  \  gs_param_typed_value *);
\end{program}
The macro is mapped to a call to \prog{xmit\_typed} and returns its return code.

Again there is a layer of type-specific functions on top of this basic
interface.
For an \prog{int}, the routine is:
\begin{program}
int param_write_int(gs_param_list *, gs_param_name, const int *);
\end{program}
These functions should be preferred.


\paragraph{Other Functions.}

The macros \prog{param\_signal\_error()}, \prog{param\_commit()} and
\prog{param\_get\_next\_key()}
can be called as if they were the following functions:
\begin{program}
int param_signal_error(gs_param_list *, gs_param_name, int);
int param_commit(gs_param_list *);
int param_get_next_key(gs_param_list *, gs_param_enumerator_t *,
\    gs_param_key_t *);
\end{program}
They call the dictionary's \prog{signal\_error}, \prog{commit} and
\prog{next\_key} routines, respectively.

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


\subsection{The Parameter Device Procedures}

To be described.	% ???

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

\subsection{Default Parameters}

\subsubsection{All Devices}

The function \prog{gx\_default\_get\_params()} writes the following
parameters into the parameter list it received as an argument~[gs~5.50]:
% See gsdparam.c and gxdevcli.h.
\begin{quote}	% ??? Find a better solution.
  \normalUS
  \def\a{$^*$}	% asterisk
  \halign{\quad\prog{#}\hfil\quad& \prog{#}\hfil\quad&
      \vtop{\raggedright\hsize=5cm #\strut}\hfil\cr
      % ??? Improve baseline distance.
    \omit\quad Name\hfil & \omit Type and device variable or value\hfil &
      Remarks\cr
    \noalign{\smallskip\nointerlineskip
      \hbox{\dimen0=\hsize \advance\dimen0 by -2em
	\quad \vrule depth 0.4pt height 0pt width \dimen0}
      \smallskip}
    .HWMargins\a&	float HWMargins[4]&\cr
    .IgnoreNumCopies\a&	bool IgnoreNumCopies&\cr
    .MarginsHWResolution& float MarginsHWResolution[2]&\cr
    .MediaSize\a&	float MediaSize[2]&\cr
    BitsPerPixel&	int color_info.depth&\cr
    BlueValues&		(int)(color_info.max_color + 1)&
      only set if \prog{color\_info.num\_components} is larger than 1.\cr
    ColorValues&	(long)(1L << color_info.depth)&
      only set if \prog{color\_info.num\_components} is larger than 1.\cr
    Colors&		int color_info.num_components&	\cr
    GraphicsAlphaBits&	int&
      a value returned by the device procedure \prog{get_alpha_bits}\cr
    GrayValues&		(int)(color_info.max_gray + 1)&\cr
    GreenValues&	(int)(color_info.max_color + 1)&
      only set if \prog{color\_info.num\_components} is larger than 1.\cr
    HWColorMap&		& returned as a string\cr	% ???
    HWResolution\a&	float HWResolution[2]& \cr
    HWSize\a&		float [2]&
      initialized with \prog{width} and \prog{height} (in this order)\cr
    ImagingBBox\a&	\textrm{null or} float ImagingBBox[4]&
      the type depends on \prog{bool ImagingBBox_set}\cr
    Margins\a&		float Margins[2]&	\cr
    Name&		const char *dname& treated as a string\cr
    NumCopies\a&	\textrm{null or} int NumCopies&
      only read or written if \prog{NumCopies\_set} is not negative.
      The null value is returned if \prog{NumCopies\_set} is zero.\cr
    OutputDevice&	const char *dname& treated as a name\cr
    PageCount&		long PageCount&	\cr
    PageSize\a&		float MediaSize[2]&
      only set if \prog{PAGESIZE_IS_MEDIASIZE} was defined during
      compilation which it is~[gs~5.50].\cr
    ProcessColorModel&	\vtop{\raggedright\hsize=5cm
      \textrm{a name derived from
      \prog{color\_info.num\_components},
      see section~\ref{NativeColourSpaces}}\strut}\hfil\cr
    RedValues&		(int)(color_info.max_color + 1)&
      only set if \prog{color\_info.num\_components} is larger than 1.\cr
    TextAlphaBits&	int&
      a value returned by the device procedure \prog{get_alpha_bits}\cr
  }
\end{quote}

The function \prog{gx\_default\_put\_params()} reads the same parameters from
its arguments list,
but copies only some of them into the device instance.
These writable parameters are marked with an asterisk in the preceding list.
The others are accessed in order to check that they are defined at all,
that they have the right type or that their value satisfies certain constraints.
For example,
\ps{PageCount} must be defined and
be either \ps{null} or a \prog{long} value agreeing with the value present
in the \prog{PageCount} field in the device instance.

In addition the default put procedure also accesses \prog{\%MediaSource} and
\prog{\%MediaDestination} but only to check that these parameters have values
of integer type.

Before \prog{gx\_default\_put\_params()} actually modifies any parameters it
calls \prog{param\_commit()} for the parameter list after having called all
the necessary routines for reading the known parameters
into temporary variables.
If the commit routine returns a negative value,
processing terminates without making changes in the device structure.

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

\subsubsection{The \textit{prn\/} Device}

The function \prog{gdev\_prn\_get\_params()} first calls
\prog{gx\_default\_get\_params()} and then writes the following parameters
into the parameter list it received as an argument:
\begin{quote}	% ??? Find a better solution.
  \normalUS
  \def\a{$^*$}
  \halign{\quad\prog{#}\hfil\quad& \prog{#}\hfil\quad&
      \vtop{\raggedright\hsize=5cm #\strut}\hfil\cr
      % ??? Improve baseline distance.
    \omit\quad Name\hfil & \omit Type and device variable or value\hfil &
      Remarks\cr
    \noalign{\smallskip\nointerlineskip
      \hbox{\dimen0=\hsize \advance\dimen0 by -2em
	\quad \vrule depth 0.4pt height 0pt width \dimen0}
      \smallskip}
    BandBufferSpace&	long space_params.band.BandBufferSpace&	\cr
    BandHeight&		int  space_params.band.BandHeight&	\cr
    BandWidth&		int  space_params.band.BandWidth&	\cr
    BufferSpace&	long space_params.BufferSpace&	\cr
    Duplex\a&		\textrm{null or} bool Duplex&
	only read or written if \prog{Duplex\_set} is not negative.
	A null value is returned if \prog{Duplex\_set} is zero.\cr
    MaxBitmap&		long space_params.MaxBitmap&\cr
    OpenOutputFile\a&	bool OpenOutputFile&\cr
    OutputFile\a&	char fname[]&	treated as a string\cr
    ReopenPerPage\a&	bool ReopenPerPage&\cr
  }
\end{quote}
The function \prog{gdev\_prn\_put\_params()} accesses the same parameters
as \prog{gx\_default\_get\_params()}
and finally calls \prog{gx\_default\_put\_params()}.
Only those parameters marked with an asterisk, however,
are usually copied into the device instance.
The others will be copied only
if the field \prog{space\_params.params\_\-are\_\-read\_\-only} is \prog{false}
(then they must also satisfy some constraints),
otherwise their values must agree with those in the device instance.

In addition the put function also accesses
\prog{InputAttributes} and \prog{OutputAttributes}
and checks that they are dictionaries if defined.

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

\subsection{The Basic Access Routines in PostScript}

A device's parameters can be read with \ps{getdeviceprops} and modified by
\ps{putdeviceprops}~\cite{Language5.50}.
The first is based on the operator \ps{.getdeviceparams},
the second on \ps{.putdeviceparams}.

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

\subsubsection{Reading}

The operator \ps{.getdeviceparams} accepts either a \ps{null} value or a
dictionary of keys\footnote{Values are simply duplicates of the keys.}.
In the second case, only the specified device parameters are fetched.
The operator puts a mark object on the stack and on top of it the
names and values of those parameters which it could find.
If the caller requested a parameter which cannot be found
that request will be ignored without indicating an error.

\ifdraft
??? CHECK
\fi

This operator is implemented in \prog{zgetdeviceparams()} which calls
\prog{zget\_device\_params()},
a function introduced to reduce duplicate code.
% See zdevice.c.
This function first prepares an instance of type \prog{stack\_param\_list}
by connecting it with the operand stack
and then calls \prog{gs\_get\_device\_or\_hardware\_params()} for the device
with this list.

\ifdraft
??? Discuss selection.
\fi

The function \prog{gs\_get\_device\_or\_hardware\_params()} calls
\prog{gx\_device\_set\_procs()},
supplies default values for some device procedures if necessary,
and finally passes the parameter list to the \prog{get\_params} procedure.

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

\subsubsection{Writing}

The operator \ps{.putdeviceparams} is implemented in \prog{zputdeviceparams()}.
Its behaviour with respect to unrecognized keys has to be requested as
either to ignore them or to generate an \ps{undefined} error
(as \ps{putdeviceprops} does).

The implementation first prepares an instance of type \prog{stack\_param\_list}
and then calls \prog{gs\_put\-device\-params()} for the device
with this list.
If the return code is negative (error), the function returns.
Otherwise, some special processing is done under certain circumstances
and finally the macro \prog{clear\_\-page\-device()} is called for the graphics
state.

\ifdraft
??? Add description of error processing for undefined values.
\fi

The function \prog{gs\_putdeviceparams()} calls
\prog{gx\_device\_set\_procs()},
supplies default values for some device procedures if necessary,
and then calls the \prog{put\_params} procedure with the parameter list.
The return code from \prog{gs\_putdeviceparams()} is the code returned by the
device procedure provided it is negative or the device was closed before the
call or it is still open afterwards;
otherwise (no error and th