The R Project SVN – R – Diff – /trunk/src/include/R_ext/GraphicsDevice.h

-/**************************
- * A first hack at a possible new device API
- **************************
- */
 /* New device driver structure
  * NOTES:
  * 1. All locations and dimensions are in device coordinates.
  * 2. I found this comment in the doc for dev_Open -- looks nasty
  *    what dev_StrWidth would give if font metric information is
  *    not available.  I guess having both allows the developer
  *    to decide when to ask for which sort of value, and to decide
  *    what to do when font metric information is not available.
  *    And why not a dev_StrHeight?
- * 4. Replaced dev_Resize with dev_Size
- * 5. Do I make "cex" and "ps" part of the graphics engine or
- *    part of R base graphics?  If not part of the graphics engine,
- *    then how should the graphics engine specify text size?
- *    For now, they are part of the graphics engine.
- *    Similar comments apply for "font".
- * 6. Should "ipr", "asp", and "cra" be in the device description?
+ * 4. Should "ipr", "asp", and "cra" be in the device description?
  *    If not, then where?
  *    I guess they don't need to be if no device makes use of them.
  *    On the other hand, they would need to be replaced by a device
  *    call that R base graphics could use to get enough information
  *    to figure them out.  (e.g., some sort of dpi() function to
  *    complement the size() function.)
- * 7. Is dev_Dot used anywhere?
  */
 typedef struct {
     /* The first element is a boolean indicating whether this is
      * a new device driver (always 1) -- the old device driver structure
      * has had a similar element added (which will always be 0)
+     *
 				 * was last initialised
 				 */
     /********************************************************
      * Device procedures.
      ********************************************************/
+    /*
+     * ---------------------------------------
+     * GENERAL COMMENT ON GRAPHICS PARAMETERS:
+     * ---------------------------------------
+     * Graphical parameters are now passed in a graphics context
+     * structure (R_GE_gcontext*) rather than individually.
+     * Each device action should extract the parameters it needs
+     * and ignore the others.  Thought should be given to which
+     * parameters are relevant in each case -- the graphics engine
+     * does not REQUIRE that each parameter is honoured, but if
+     * a parameter is NOT honoured, it might be a good idea to
+     * issue a warning when a parameter is not honoured (or at
+     * the very least document which parameters are not honoured
+     * in the user-level documentation for the device).  [An example
+     * of a parameter that may not be honoured by many devices is
+     * transparency.]
+     */
     /*
      * device_Activate is called when a device becomes the
      * active device.  For example, it can be used to change the
      * title of a window to indicate the active status of
      * the device to the user.  Not all device types will
      * If "fill" is NA_INTEGER then the circle should not
      * be filled.
      * An example is ...
+     *
      * static void X11_Circle(double x, double y, double r,
-     *		              int col, int fill, double gamma,
-     *                        int lty, double lwd,
+     *                        R_GE_gcontext *gc,
      *                        NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   col, fill, gamma, lty, lwd
      */
     void (*circle)();
     /*
      * device_Clip is given the left, right, bottom, and
      * top of a rectangle (in DEVICE coordinates).
      * device_Line should have the side-effect that a single
      * line is drawn (from x1,y1 to x2,y2)
      * An example is ...
+     *
      * static void X11_Line(double x1, double y1, double x2, double y2,
-     *		            int col, double gamma, int lty, double lwd,
+     *                      R_GE_gcontext *gc,
      *                      NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   col, gamma, lty, lwd
      */
     void (*line)();
     /*
      * device_MetricInfo should return height, depth, and
      * width information for the given character in DEVICE
      * and for exact centering of text (see GText)
      * If the device cannot provide metric information then
      * it MUST return 0.0 for ascent, descent, and width.
      * An example is ...
+     *
-     * static void X11_MetricInfo(int c, int font, double cex, double ps,
+     * static void X11_MetricInfo(int c,
+     *                            R_GE_gcontext *gc,
      *                            double* ascent, double* descent,
      *                            double* width, NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   font, cex, ps
      */
     void (*metricInfo)();
     /*
      * device_Mode is called whenever the graphics engine
      * starts drawing (mode=1) or stops drawing (mode=0)
      * device (e.g., X11) or moving to a new page
      * (e.g., postscript)
      * An example is ...
+     *
+     *
-     * static void X11_NewPage(int fill, double gamma, NewDevDesc *dd);
+     * static void X11_NewPage(R_GE_gcontext *gc,
+     *                         NewDevDesc *dd);
+     *
      */
     void (*newPage)();
     /*
      * device_Open is not usually called directly by the
      * If "col" is NA_INTEGER don't draw the border
      * If "fill" is NA_INTEGER don't fill the polygon
      * An example is ...
+     *
      * static void X11_Polygon(int n, double *x, double *y,
-     *		               int col, int fill, double gamma,
-     *                         int lty, double lwd,
+     *                         R_GE_gcontext *gc,
      *                         NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   col, fill, gamma, lty, lwd
      */
     void (*polygon)();
     /*
      * device_Polyline should have the side-effect that a
      * series of line segments are drawn using the given x
      * and y values.
      * An example is ...
+     *
      * static void X11_Polyline(int n, double *x, double *y,
-     *		               int col, double gamma,
-     *                         int lty, double lwd,
+     *                          R_GE_gcontext *gc,
      *                          NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   col, gamma, lty, lwd
      */
     void (*polyline)();
     /*
      * device_Rect should have the side-effect that a
      * rectangle is drawn with the given locations for its
      * If "fill" is NA_INTEGER then the rectangle should not
      * be filled.
      * An example is ...
+     *
      * static void X11_Rect(double x0, double y0, double x1, double y1,
-     *		            int col, int fill, double gamma,
-     *                      int lty, double lwd,
+     *                      R_GE_gcontext *gc,
      *                      NewDevDesc *dd);
+     *
      */
     void (*rect)();
     /*
+     *
      * static void X11_Size(double *left, double *right,
      *                      double *bottom, double *top,
      *                      NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   col, fill, gamma, lty, lwd
      */
     void (*size)();
     /*
      * device_StrWidth should return the width of the given
      * string in DEVICE units.
      * An example is ...
+     *
-     * static double X11_StrWidth(char *str, int font, double cex, double ps,
+     * static double X11_StrWidth(char *str,
+     *                            R_GE_gcontext *gc,
      *                            NewDevDesc *dd)
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   font, cex, ps
      */
     double (*strWidth)();
     /*
      * device_Text should have the side-effect that the
      * given text is drawn at the given location.
      * The text should be rotated according to rot (degrees)
      * An example is ...
+     *
      * static void X11_Text(double x, double y, char *str,
      *                      double rot, double hadj,
-     *		            int col, double gamma,
-     *                      int font, double cex, double ps,
+     *                      R_GE_gcontext *gc,
      * 	                    NewDevDesc *dd);
+     *
+     * R_GE_gcontext parameters that should be honoured (if possible):
+     *   font, cex, ps, col, gamma
      */
     void (*text)();
 } NewDevDesc;
 	/********************************************************/

The R Project SVN R

(root)/trunk/src/include/R_ext/GraphicsDevice.h – Rev 19874 → 27236