The R Project SVN
R
(root)/trunk/src/include/Graphics.h – Rev 3243
Rev 2566 | Go to most recent revision | Blame | Last modification | View Log | Download | RSS feed
/** R : A Computer Language for Statistical Data Analysis* Copyright (C) 1995, 1996 Robert Gentleman and Ross Ihaka** This program is free software; you can redistribute it and/or modify* it under the terms of the GNU General Public License as published by* the Free Software Foundation; either version 2 of the License, or* (at your option) any later version.** This program is distributed in the hope that it will be useful,* but WITHOUT ANY WARRANTY; without even the implied warranty of* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the* GNU General Public License for more details.** You should have received a copy of the GNU General Public License* along with this program; if not, write to the Free Software* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.*/#ifndef GRAPHICS_H_#define GRAPHICS_H_#include "Defn.h"#ifndef NA_REAL#define NA_REAL R_NaReal#endif#ifndef NA_INTEGER#define NA_INTEGER R_NaInt#endif#ifdef Macintosh#include <fp.h>#else#include <math.h>#endif#ifdef Windows#include <windows.h>#endif#include <float.h>#include <stdlib.h>#include <stdio.h>/** Some Notes on Color** R uses a 24-bit color model. Colors are specified in 32-bit* integers which are partitioned into 4 bytes as follows.** <-- most sig least sig -->* +-------------------------------+* | 0 | blue | green | red |* +-------------------------------+** The red, green and blue bytes can be extracted as follows.** red = ((color ) & 255)* green = ((color >> 8) & 255)* blue = ((color >> 16) & 255)*/#define R_RGB(r,g,b) ((r)|((g)<<8)|((b)<<16))#define R_RED(col) (((col) )&255)#define R_GREEN(col) (((col)>> 8)&255)#define R_BLUE(col) (((col)>>16)&255)#define COLOR_TABLE_SIZE 256#ifdef Unix#define LTY_SOLID 0#define LTY_DASHED 4 + (4<<4)#define LTY_DOTTED 1 + (3<<4)#define LTY_DOTDASH 1 + (3<<4) + (4<<8) + (3<<12)#endif#ifdef Windows#define LTY_SOLID PS_SOLID#define LTY_DASHED PS_DASH#define LTY_DOTTED PS_DOT#define LTY_DOTDASH PS_DASHDOT#endif#define MAX_LAYOUT_ROWS 15#define MAX_LAYOUT_COLS 15/* possible coordinate systems (for specifying locations) */#define DEVICE 0 /* native device coordinates (rasters) */#define NDC 1 /* normalised device coordinates x=(0,1), y=(0,1) */#define INCHES 13 /* inches x=(0,width), y=(0,height) */#define NIC 6 /* normalised inner region coordinates (0,1) */#define OMA1 2 /* outer margin 1 (bottom) x=NIC, y=LINES */#define OMA2 3 /* outer margin 2 (left) */#define OMA3 4 /* outer margin 3 (top) */#define OMA4 5 /* outer margin 4 (right) */#define NFC 7 /* normalised figure region coordinates (0,1) */#define NPC 16 /* normalised plot region coordinates (0,1) */#define USER 12 /* user/data/world corrdinates *//* x=(xmin,xmax), y=(ymin,ymax) */#define MAR1 8 /* figure margin 1 (bottom) x=USER(x), y=LINES */#define MAR2 9 /* figure margin 2 (left) x=USER(y) y=LINES */#define MAR3 10 /* figure margin 3 (top) x=USER(x), y=LINES */#define MAR4 11 /* figure margin 4 (right) x=USER(y) y=LINES *//* possible units (for specifying dimensions) *//* all of the above, plus ... */#define LINES 14 /* multiples of a line in the margin (mex) */#define CHARS 15 /* multiples of text height (cex) */#define R_MaxDevices 64typedef unsigned int rcolor;typedef struct {double ax;double bx;double ay;double by;} GTrans;struct colorDataBaseEntry {char *name; /* X11 Color Name */char *rgb; /* #RRGGBB String */unsigned int code; /* Internal R Color Code */};typedef struct colorDataBaseEntry ColorDataBaseEntry;extern int ColorTableSize;extern unsigned int ColorTable[];extern ColorDataBaseEntry ColorDataBase[];extern char *DefaultPalette[];/* Graphics State:** The following structure defines state for a graphics device driver.* Two copies are kept; the ``default'' set of values, and a set which* can be modified during calls to an application program. When a* new graphics frame is started, the values revert to the defaults**/typedef struct {/* Basic Device Driver Properties *//* These MUST be set by device drivers on open *//* These parameters cannot be set by the user *//* although left, right, bottom, and top can be *//* interrogated indirectly (i.e., par("din")) *//* and cra can be interrogated directly (i.e., par("cra")) */double left; /* left raster coordinate */double right; /* right raster coordinate */double bottom; /* bottom raster coordinate */double top; /* top raster coordinate */double xCharOffset; /* x character addressing offset */double yCharOffset; /* y character addressing offset */double yLineBias; /* 1/2 interline space as fraction of line height */int canResizePlot; /* can the graphics surface be resized */int canChangeFont; /* device has multiple fonts */int canRotateText; /* text can be rotated */int canResizeText; /* text can be resized */int canClip; /* Hardware clipping *//* a couple of the GRZ-like parameters that have to be *//* set by the device */double ipr[2]; /* Inches per raster; [0]=x, [1]=y */double asp; /* Pixel aspect ratio = ipr[1]/ipr[0] */double cra[2]; /* Character size in rasters; [0]=x, [1]=y *//* Plot State *//* When the device driver is started this is 0 *//* After the first call to plot.new it is 1 *//* Every graphics operation except plot.new *//* should fail if state = 0 *//* This is checked at the highest internal function *//* level (e.g., do_lines, do_axis, do_plot_xy, ...) */int state; /* Plot State */int valid; /* valid layout ? *//* GRZ-like Graphics Parameters *//* ``The horror, the horror ... '' *//* Marlon Brando - Appocalypse Now *//* General Parameters -- set and interrogated directly */double adj; /* String adjustment */int ann; /* Should annotation take place */int ask; /* User confirmation of ``page eject'' */rcolor bg; /* **R ONLY** Background color */int bty; /* Box type */double cex; /* Character expansion */rcolor col; /* Plotting Color */double crt; /* Character/string rotation */double din[2]; /* device size in inches */int err; /* Error repporting level */rcolor fg; /* **R ONLY** Foreground Color */int font; /* Text font */double gamma; /* Device Gamma Correction */int lab[3]; /* Axis labelling *//* [0] = # ticks on x-axis *//* [1] = # ticks on y-axis *//* [2] = length of axis labels */int las; /* Label style (rotation) */int lty; /* Line texture */double lwd; /* Line width */double mgp[3]; /* Annotation location *//* [0] = location of axis title *//* [1] = location of axis label *//* [2] = location of axis line */double mkh; /* Mark size in inches */int pch; /* Plotting character */int ps; /* Text & symbol pointsize */int smo; /* Curve smoothness */double srt; /* String Rotation */double tck; /* Tick size as in S */double tcl; /* Tick size in "lines" */double tmag; /* **R ONLY** Title Magnification */int type; /* type of plot desired */double xaxp[3]; /* X Axis annotation *//* [0] = coordinate of lower tick *//* [1] = coordinate of upper tick *//* [2] = num tick intervals *//* almost always used internally */int xaxs; /* X Axis style */int xaxt; /* X Axis type */int xpd; /* Clip to plot region indicator */int oldxpd;double yaxp[3]; /* Y Axis annotation */int yaxs; /* Y Axis style */int yaxt; /* Y Axis type */int xlog; /* Log Axis for X */int ylog; /* Log Axis for Y *//* Annotation Parameters */float cexbase; /* Base character size */float cexmain; /* Main title size */float cexlab; /* xlab and ylab size */float cexsub; /* Sub title size */float cexaxis; /* Axis label size */int fontmain; /* Main title font */int fontlab; /* Xlab and ylab font */int fontsub; /* Subtitle font */int fontaxis; /* Axis label fonts */int colmain; /* Main title color */int collab; /* Xlab and ylab color */int colsub; /* Subtitle color */int colaxis; /* Axis label color *//* Layout Parameters */int layout; /* has a layout been specified */int numrows;int numcols;int currentFigure;int lastFigure;double heights[MAX_LAYOUT_ROWS];double widths[MAX_LAYOUT_COLS];int cmHeights[MAX_LAYOUT_ROWS];int cmWidths[MAX_LAYOUT_COLS];int order[MAX_LAYOUT_ROWS][MAX_LAYOUT_COLS];int rspct; /* 0 = none, 1 = full, 2 = see respect */int respect[MAX_LAYOUT_ROWS][MAX_LAYOUT_COLS];int mfind; /* By row/col indicator *//* Layout parameters which can be set directly by the *//* user (e.g., par(fig=c(.5,1,0,1))) or otherwise are *//* calculated automatically *//* NOTE that *Units parameters are for internal use only */double fig[4]; /* (current) Figure size (proportion) *//* [0] = left, [1] = right *//* [2] = bottom, [3] = top */double fin[2]; /* (current) Figure size (inches) *//* [0] = width, [1] = height */int fUnits; /* (current) figure size units */int defaultFigure; /* calculate figure from layout ? */double plt[4]; /* (current) Plot size (proportions) *//* [0] = left, [1] = right *//* [2] = bottom, [3] = top */double pin[2]; /* (current) plot size (inches) *//* [0] = width, [1] = height */int pUnits; /* (current) plot size units */int defaultPlot; /* calculate plot from figure - margins ? *//* Layout parameters which are set directly by the user */double mar[4]; /* Plot margins in lines */double mai[4]; /* Plot margins in inches *//* [0] = bottom, [1] = left *//* [2] = top, [3] = right */int mUnits; /* plot margin units */double mex; /* Margin expansion factor */double oma[4]; /* Outer margins in lines */double omi[4]; /* outer margins in inches */double omd[4]; /* outer margins in NDC *//* [0] = bottom, [1] = left *//* [2] = top, [3] = right */int oUnits; /* outer margin units */int pty; /* Plot type *//* Layout parameters which can be set by the user, but *//* almost always get automatically calculated anyway */double usr[4]; /* Graphics window *//* [0] = xmin, [1] = xmax *//* [2] = ymin, [3] = ymax *//* The logged usr parameter; if xlog, use logusr[0:1] *//* if ylog, use logusr[2:3] */double logusr[4];/* Layout parameter: Internal flags */int new; /* Clean plot ? */int devmode; /* creating new image or adding to existing one *//* Coordinate System Mappings *//* These are only used internally (i.e., cannot be *//* set directly by the user) *//* The reliability of these parameters relies on *//* the fact that plot.new is the *//* first graphics operation called in the creation *//* of a graph *//* udpated per plot.new */double xNDCPerChar; /* Nominal character width (NDC) */double yNDCPerChar; /* Nominal character height (NDC) */double xNDCPerLine; /* Nominal line width (NDC) */double yNDCPerLine; /* Nominal line height (NDC) */double xNDCPerInch; /* xNDC -> Inches */double yNDCPerInch; /* yNDC -> Inches *//* updated per plot.new and if inner2dev changes */GTrans fig2dev; /* Figure to device *//* udpated per DevNewPlot and if ndc2dev changes */GTrans inner2dev; /* Inner region to device *//* udpated per device resize */GTrans ndc2dev; /* NDC to raw device *//* updated per plot.new and per plot.window */GTrans win2fig; /* Window to figure mapping *//* NOTE: if user has not set fig and/or plt then *//* they need to be updated per plot.new too *//* device operations */int (*open)();void (*close)();void (*activate)();void (*deactivate)();void (*resize)();void (*newPage)();void (*clip)();double (*strWidth)();void (*line)();void (*polyline)();void (*text)();void (*dot)();void (*rect)();void (*circle)();void (*polygon)();int (*locator)();void (*mode)();void (*hold)();void (*metricInfo)();} GPar;typedef struct {GPar dp; /* current device default parameters */GPar gp; /* current device current parameters */GPar dpSaved; /* saved device default parameters */void *deviceSpecific; /* pointer to device specific parameters */int displayListOn; /* toggle for display list status */SEXP displayList; /* display list */} DevDesc;/* Drivers from ../main/devices.c , description there: */int PSDeviceDriver(DevDesc*, char*, char*, char*,char*, char*, double, double, double, double);int PicTeXDeviceDriver(DevDesc*, char*, char*, char*, double, double, int);/*ifdef Unix : ../unix/devX11.h only in few places*/#ifdef Win32int WinDeviceDriver(char**, int, double*, int);#endif#ifdef Macintoshint MacDeviceDriver(char**, int, double*, int);#endif/* User Callable Functions *//*-------------------------------------------------------------------** DEVICE FUNCTIONS are concerned with the creation and destruction* of devices.**//* Return a pointer to the current device. */DevDesc* CurrentDevice();/* Return a pointer to a device which is identified by number */DevDesc* GetDevice(int);/* Initialise internal device structures. */void InitGraphics(void);/* Kill device which is identified by number. */void KillDevice(DevDesc*);/* Kill all active devices (used at shutdown). */void KillAllDevices();/* Is the null device the current device? */int NoDevices();/* How many devices exist ? (>= 1) */int NumDevices();/* Get the index of the specified device. */int deviceNumber(DevDesc*);/* Create a new device. */int StartDevice(SEXP, SEXP, int, SEXP, int);void DevNull(void);/*- these added by MM, eliminating -Wall "implicit declaration"s: */void recordGraphicOperation(SEXP, SEXP, DevDesc*);void initDisplayList();void copyDisplayList(int);void playDisplayList(DevDesc*);void inhibitDisplayList(DevDesc*);/*-------------------------------------------------------------------** DEVICE UTILITIES are concerned with providing information* for R interpreted functions.**//* Return the number of the current device. */int curDevice();/* Return the number of the next device. */int nextDevice(int);/* Return the number of the previous device. */int prevDevice(int);/* Make the specified device (specified by number) the current device */int selectDevice(int);/* Kill device which is identified by number. */void killDevice(int);/* ...NO DOC... */void addDevice(DevDesc *);/*-------------------------------------------------------------------** GPAR FUNCTIONS are concerned with operations on the* entire set of graphics parameters for a device* (e.g., initialisation, saving, and restoring)*//* Default the settings for general graphical parameters* (i.e., defaults that do not depend on the device type: */void GInit(GPar*);/* Reset the current graphical parameters from the default ones: */void GRestore(DevDesc*);/* Make a temporary copy of the current parameters */void GSavePars(DevDesc*);/* Restore the temporary copy saved by GSavePars */void GRestorePars(DevDesc*);/* More Programmer GPar functions */void ProcessInlinePars(SEXP, DevDesc*);void Specify2(char*, SEXP, DevDesc*);SEXP FixupPch(SEXP, DevDesc*);SEXP FixupLty(SEXP, DevDesc*);SEXP FixupFont(SEXP); /* FIXME: need 2nd arg? */SEXP FixupCol(SEXP, DevDesc*);SEXP FixupCex(SEXP);/*-------------------------------------------------------------------** DEVICE STATE FUNCTIONS are concerned with getting and setting* the current state of the device; is it ready to be drawn into?*//* has plot.new been called yet? */void GCheckState(DevDesc*);/* Set to 1 when plot.new succeeds* Set to 0 when don't want drawing to go ahead */void GSetState(int, DevDesc*);/*-------------------------------------------------------------------** GRAPHICAL PRIMITIVES are the generic front-end for the functions* that every device driver must provide.** NOTE that locations supplied to these functions may be in any* of the valid coordinate systems (each function takes a "coords"* parameter to indicate the coordinate system); the device-specific* version of the function is responsible for calling GConvert to get* the location into device coordinates.**//* Draw a circle, centred on (x,y) with radius r (in inches). */void GCircle(double, double, int, double, int, int, DevDesc*);/* Set clipping region (based on current setting of dd->gp.xpd).* Only clip if new clipping region is different from the current one */void GClip(DevDesc*);/* Always clips */void GForceClip(DevDesc*);/* Draw a line from (x1,y1) to (x2,y2): */void GLine(double, double, double, double, int, DevDesc*);/* Return the location of the next mouse click: */int GLocator(double*, double*, int, DevDesc*);/* Return the height, depth, and width of the specified* character in the specified units: */void GMetricInfo(int, double*, double*, double*, int, DevDesc*);/* Set device "mode" (drawing or not drawing) here for windows and mac drivers.*/void GMode(DevDesc*, int);/* Draw a polygon using the specified lists of x and y values: */void GPolygon(int, double*, double*, int, int, int, DevDesc*);/* Draw series of straight lines using the specified lists of x and y values: */void GPolyline(int, double*, double*, int, DevDesc*);/* Draw a rectangle given two opposite corners: */void GRect(double, double, double, double, int, int, int, DevDesc*);/* Return the height of the specified string in the specified units: */double GStrHeight(char*, int, DevDesc*);/* Return the width of the specified string in the specified units */double GStrWidth(char*, int, DevDesc*);/* Draw the specified text at location (x,y) with the specified* rotation and justification: */void GText(double, double, int, char*, double, double, double, DevDesc*);void GStartPath(DevDesc*);void GEndPath(DevDesc*);void GMathText(double, double, int, SEXP, double, double, double, DevDesc*);void GMMathText(SEXP, int, double, int, double, int, DevDesc*);/*-------------------------------------------------------------------** GRAPHICAL UTILITIES are functions that produce graphical output* using the graphical primitives (i.e., they are generic - NOT* device-specific).**//* Draw a line from (x1,y1) to (x2,y2) with an arrow head* at either or both ends. */void GArrow(double, double, double, double, int, double, double, int, DevDesc*);/* Draw a box around specified region:* 1=plot region, 2=figure region, 3=inner region, 4=device. */void GBox(int, DevDesc*);/* Return a "nice" min, max and number of intervals for a given* range on a linear or _log_ scale, respectively: */void GPretty(double*, double*, int*);void GLPretty(double*, double*, int*);/* Draw text in margins. */void GMtext(char*, int, double, int, double, int, DevDesc*);/* Draw one of the predefined symbols (circle, square, diamond, ...) */void GSymbol(double, double, int, int, DevDesc*);double GExpressionHeight(SEXP, int, DevDesc*);double GExpressionWidth(SEXP, int, DevDesc*);/*-------------------------------------------------------------------** COLOUR CODE is concerned with the internals of R colour representation**//* Convert an R colour specification (which might be a number or *//* a string) into an internal colour specification. */unsigned int RGBpar(SEXP, int, DevDesc*);/*-------------------------------------------------------------------** LINE TEXTURE CODE is concerned with the internals of R* line texture representation.*/unsigned int LTYpar(SEXP, int);SEXP LTYget(unsigned int);/*----------------------------------------------------------------------** TRANSFORMATIONS are concerned with converting locations between* coordinate systems and dimensions between different units.*//* Convert an R unit (e.g., "user") into an internal unit (e.g., USER)> */int GMapUnits(int);/* Convert a location from one coordinate system to another: */void GConvert(double*, double*, int, int, DevDesc*);/* Convert an x/y-dimension from one set of units to another: */double GConvertXUnits(double, int, int, DevDesc*);double GConvertYUnits(double, int, int, DevDesc*);/* Set up the different regions on a device (i.e., inner region,* figure region, plot region) and transformations for associated* coordinate systems (called whenever anything that affects the* coordinate transformations changes):*/void GReset(DevDesc*);/* Set up the user coordinate transformations: */void GMapWin2Fig(DevDesc*);/* Set up the device for a new plot by Resetting graphics parameters* and Resetting the regions and coordinate Systems */DevDesc *GNewPlot(int, int);/* Set up the user coordinates based on the axis limits */void GScale(double, double, int, DevDesc*);/* Set up the axis limits based on the user coordinates */void GSetupAxis(int, DevDesc*);/* Return row and column of current figure in the layout matrix */void currentFigureLocation(int*, int*, DevDesc*);double Log10(double);double xDevtoNDC(double x, DevDesc *dd);double yDevtoNDC(double y, DevDesc *dd);double xDevtoNFC(double x, DevDesc *dd);double yDevtoNFC(double y, DevDesc *dd);double xNPCtoUsr(double, DevDesc*);double yNPCtoUsr(double, DevDesc*);/* Miscellaneous (from graphics.c & colors.c) */unsigned int rgb2col(char *);unsigned int name2col(char *);unsigned int char2col(char *s);/* rgb2col() or name2col() */char* col2name(unsigned int);unsigned int str2col(char *s, DevDesc *dd);unsigned int ScaleColor(double x);char* RGB2rgb(unsigned int, unsigned int, unsigned int);int StrMatch(char *s, char *t);#endif