The R Project SVN
R
(root)/branches/R-4-4-branch/src/include/R_ext/GraphicsEngine.h – Rev 86207
Rev 84150 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed
/** R : A Computer Language for Statistical Data Analysis* Copyright (C) 2001-21 The R Core Team.** This header file is free software; you can redistribute it and/or modify* it under the terms of the GNU Lesser General Public License as published by* the Free Software Foundation; either version 2.1 of the License, or* (at your option) any later version.** This file is part of R. R is distributed under the terms of the* GNU General Public License, either Version 2, June 1991 or Version 3,* June 2007. See doc/COPYRIGHTS for details of the copyright status of R.** 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 Lesser General Public License for more details.** You should have received a copy of the GNU Lesser General Public License* along with this program; if not, a copy is available at* https://www.R-project.org/Licenses/*//* Used by graphics.c, grid and by third-party graphics devices */#ifndef R_GRAPHICSENGINE_H_#define R_GRAPHICSENGINE_H_#ifdef __cplusplusextern "C" {#endif/** The current graphics engine (including graphics device) API version* MUST be integer** This number should be bumped whenever there are changes to* GraphicsEngine.h or GraphicsDevice.h so that add-on packages* that compile against these headers (graphics systems such as* graphics and grid; graphics devices such as gtkDevice, RSvgDevice)* can detect any version mismatch.** Version 1: Introduction of the version number.* Version 2: GEDevDesc *dd dropped from GEcontourLines().* Version 3: R_GE_str2col() added to API. (r41887)* Version 4: UTF-8 text hooks, useRotatedTextInContour,* add newFrameConfirm() to NewDevDesc.* New API: GEaddDevice[2] GEgetDevice, GEkillDevice,* ndevNumber. (R 2.7.0)* Version 5: Clean up 1.4.0/2.0.0 changes!* Remove newDevStruct from GEDevDesc and NewDevDesc.* Remove asp, dot(), hold(), open() from NewDevDesc.* Move displayList, DLlastElt, savedSnapshot from* NewDevDesc to GEDevDesc.* Add 'ask' to GEDevDesc. (R 2.8.0)* Version 6: Add dev_Raster() and dev_Cap() (R 2.11.0)* Version 7: Change graphics event handling, adding eventEnv and eventHelper()* to DevDesc. (R 2.12.0)* Version 8: Add dev_Path() (R 2.12.0)* Version 9: Add dev_HoldFlush(), haveTrans*, haveRaster,* haveCapture, haveLocator. (R 2.14.0)* Version 10: For R 3.0.0. Typedef and use 'rcolor',* Remove name2col (R_GE_str2col does the job).* Version 11: For R 3.3.0.* Official support for saving/restoring display lists* across R sessions (via recordPlot() and replayPlot())* - added grid DL to snapshots (used to be NULL)* - added this version number to snapshots (as attribute)* - added R version number to snapshots (as attribute)* - added pkgName to graphics system state info (as attribute)* Version 12: For R 3.4.0* Added canGenIdle, doIdle() and doesIdle() to devices.* Version 13: For R 4.1.0* Added graphical definitions* - linear gradients* - radial gradients* - patterns* - clipping paths* - masks* Added deviceVersion* Version 14: Added deviceClip* Version 15: For R 4.2.0* Added more graphical definitions* - groups* - paths* - luminance masks* Added capabilities* Version 16: For R 4.3.0* Added more advanced typesetting* - glyphs*/#define R_GE_definitions 13#define R_GE_deviceClip 14#define R_GE_group 15#define R_GE_glyphs 16#define R_GE_version R_GE_glyphsint R_GE_getVersion(void);void R_GE_checkVersionOrDie(int version);/* The graphics engine will only accept locations and dimensions* in native device coordinates, but it provides the following functions* for converting between a couple of simple alternative coordinate* systems and device coordinates:* DEVICE = native units of the device* NDC = Normalised device coordinates* INCHES = inches (!)* CM = centimetres (!!)*/typedef enum {GE_DEVICE = 0, /* native device coordinates (rasters) */GE_NDC = 1, /* normalised device coordinates x=(0,1), y=(0,1) */GE_INCHES = 2,GE_CM = 3} GEUnit;#define MAX_GRAPHICS_SYSTEMS 24typedef enum {/* In response to this event, the registered graphics system* should allocate and initialise the systemSpecific structure** Should return R_NilValue on failure so that engine* can tidy up memory allocation*/GE_InitState = 0,/* This event gives the registered system a chance to undo* anything done in the initialisation.*/GE_FinaliseState = 1,/* This is sent by the graphics engine prior to initialising* the display list. It give the graphics system the chance* to squirrel away information it will need for redrawing the* the display list*/GE_SaveState = 2,/* This is sent by the graphics engine prior to replaying the* display list. It gives the graphics system the chance to* restore any information it saved on the GE_SaveState event*/GE_RestoreState = 6,/* Copy system state information to the current device.* This is used when copying graphics from one device to another* so all the graphics system needs to do is to copy across* the bits required for the display list to draw faithfully* on the new device.*/GE_CopyState = 3,/* Create a snapshot of the system state that is sufficient* for the current "image" to be reproduced*/GE_SaveSnapshotState = 4,/* Restore the system state that is saved by GE_SaveSnapshotState*/GE_RestoreSnapshotState = 5,/* When replaying the display list, the graphics engine* checks, after each replayed action, that the action* produced valid output. This is the graphics system's* chance to say that the output is crap (in which case the* graphics engine will abort the display list replay).*/GE_CheckPlot = 7,/* The device wants to scale the current pointsize* (for scaling an image)* This is not a nice general solution, but a quick fix for* the Windows device.*/GE_ScalePS = 8} GEevent;/** Some line end/join constants*/typedef enum {GE_ROUND_CAP = 1,GE_BUTT_CAP = 2,GE_SQUARE_CAP = 3} R_GE_lineend;typedef enum {GE_ROUND_JOIN = 1,GE_MITRE_JOIN = 2,GE_BEVEL_JOIN = 3} R_GE_linejoin;/** A structure containing graphical parameters** This is how graphical parameters are passed from graphics systems* to the graphics engine AND from the graphics engine to graphics* devices.** Devices are not *required* to honour graphical parameters* (e.g., alpha transparency is going to be tough for some)*/typedef struct {/** Colours** NOTE: Alpha transparency included in col & fill*/int col; /* pen colour (lines, text, borders, ...) */int fill; /* fill colour (for polygons, circles, rects, ...) */double gamma; /* Gamma correction *//** Line characteristics*/double lwd; /* Line width (roughly number of pixels) */int lty; /* Line type (solid, dashed, dotted, ...) */R_GE_lineend lend; /* Line end */R_GE_linejoin ljoin; /* line join */double lmitre; /* line mitre *//** Text characteristics*/double cex; /* Character expansion (font size = fontsize*cex) */double ps; /* Font size in points */double lineheight; /* Line height (multiply by font size) */int fontface; /* Font face (plain, italic, bold, ...) */char fontfamily[201]; /* Font family *//** Definitions*/SEXP patternFill; /* Reference to a pattern fill */} R_GE_gcontext;typedef R_GE_gcontext* pGEcontext;#include <R_ext/GraphicsDevice.h> /* needed for DevDesc */typedef struct _GEDevDesc GEDevDesc;typedef SEXP (* GEcallback)(GEevent, GEDevDesc *, SEXP);typedef struct {/* An array of information about each graphics system that* has registered with the graphics engine.* This is used to store graphics state for each graphics* system on each device.*/void *systemSpecific;/** An array of function pointers, one per graphics system that* has registered with the graphics engine.** system_Callback is called when the graphics engine wants* to give a graphics system the chance to play with its* device-specific information (stored in systemSpecific)* There are two parameters: an "event" to tell the graphics* system why the graphics engine has called this function,* and the systemSpecific pointer. The graphics engine* has to pass the systemSpecific pointer because only* the graphics engine will know what array index to use.*/GEcallback callback;} GESystemDesc;struct _GEDevDesc {/** Stuff that the devices can see (and modify).* All detailed in GraphicsDevice.h*/pDevDesc dev;/** Stuff about the device that only the graphics engine sees* (the devices don't see it).*/Rboolean displayListOn; /* toggle for display list status */SEXP displayList; /* display list */SEXP DLlastElt; /* A pointer to the end of the display listto avoid traversing pairlists */SEXP savedSnapshot; /* The last element of the display list* just prior to when the display list* was last initialised*/Rboolean dirty; /* Has the device received any output? */Rboolean recordGraphics; /* Should a graphics call be stored* on the display list?* Set to FALSE by do_recordGraphics,* do_dotcallgr, and do_Externalgr* so that nested calls are not* recorded on the display list*//** Stuff about the device that only graphics systems see.* The graphics engine has no idea what is in here.* Used by graphics systems to store system state per device.*/GESystemDesc *gesd[MAX_GRAPHICS_SYSTEMS];/* per-device setting for 'ask' (use NewFrameConfirm) */Rboolean ask;/* Is a device appending a path ? */Rboolean appending;};typedef GEDevDesc* pGEDevDesc;/* functions from devices.c for use by graphics devices */#define desc2GEDesc Rf_desc2GEDesc/* map DevDesc to enclosing GEDevDesc */pGEDevDesc desc2GEDesc(pDevDesc dd);int GEdeviceNumber(pGEDevDesc);pGEDevDesc GEgetDevice(int);void GEaddDevice(pGEDevDesc);void GEaddDevice2(pGEDevDesc, const char *);void GEaddDevice2f(pGEDevDesc, const char *, const char *);void GEkillDevice(pGEDevDesc);pGEDevDesc GEcreateDevDesc(pDevDesc dev);void GEdestroyDevDesc(pGEDevDesc dd);void *GEsystemState(pGEDevDesc dd, int index);void GEregisterWithDevice(pGEDevDesc dd);void GEregisterSystem(GEcallback callback, int *systemRegisterIndex);void GEunregisterSystem(int registerIndex);SEXP GEhandleEvent(GEevent event, pDevDesc dev, SEXP data);#define fromDeviceX GEfromDeviceX#define toDeviceX GEtoDeviceX#define fromDeviceY GEfromDeviceY#define toDeviceY GEtoDeviceY#define fromDeviceWidth GEfromDeviceWidth#define toDeviceWidth GEtoDeviceWidth#define fromDeviceHeight GEfromDeviceHeight#define toDeviceHeight GEtoDeviceHeightdouble fromDeviceX(double value, GEUnit to, pGEDevDesc dd);double toDeviceX(double value, GEUnit from, pGEDevDesc dd);double fromDeviceY(double value, GEUnit to, pGEDevDesc dd);double toDeviceY(double value, GEUnit from, pGEDevDesc dd);double fromDeviceWidth(double value, GEUnit to, pGEDevDesc dd);double toDeviceWidth(double value, GEUnit from, pGEDevDesc dd);double fromDeviceHeight(double value, GEUnit to, pGEDevDesc dd);double toDeviceHeight(double value, GEUnit from, pGEDevDesc dd);/*-------------------------------------------------------------------** COLOUR CODE is concerned with the internals of R colour representation** From colors.c, used in par.c, grid/src/gpar.c*/typedef unsigned int rcolor;#define RGBpar Rf_RGBpar#define RGBpar3 Rf_RGBpar3#define col2name Rf_col2name/* Convert an element of a R colour specification (which might be anumber or a string) into an internal colour specification. */rcolor RGBpar(SEXP, int);rcolor RGBpar3(SEXP, int, rcolor);/* Convert an internal colour specification to/from a colour name */const char *col2name(rcolor col); /* used in par.c, grid *//* Convert either a name or a #RRGGBB[AA] string to internal.Because people were using it, it also converts "1", "2" ...to a colour in the palette, and "0" to transparent white.*/rcolor R_GE_str2col(const char *s);/** Some Notes on Line Textures** Line textures are stored as an array of 4-bit integers within* a single 32-bit word. These integers contain the lengths of* lines to be drawn with the pen alternately down and then up.* The device should try to arrange that these values are measured* in points if possible, although pixels is ok on most displays.** If newlty contains a line texture description it is decoded* as follows:** ndash = 0;* for(i=0 ; i<8 && newlty & 15 ; i++) {* dashlist[ndash++] = newlty & 15;* newlty = newlty>>4;* }* dashlist[0] = length of pen-down segment* dashlist[1] = length of pen-up segment* etc** An integer containing a zero terminates the pattern. Hence* ndash in this code fragment gives the length of the texture* description. If a description contains an odd number of* elements it is replicated to create a pattern with an* even number of elements. (If this is a pain, do something* different its not crucial).**//*--- The basic numbered & names line types; Here device-independent:e.g. "dashed" == "44", "dotdash" == "1343"*//* NB: was also in Rgraphics.h in R < 2.7.0 */#define LTY_BLANK -1#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)#define LTY_LONGDASH 7 + (3<<4)#define LTY_TWODASH 2 + (2<<4) + (6<<8) + (2<<12)R_GE_lineend GE_LENDpar(SEXP value, int ind);SEXP GE_LENDget(R_GE_lineend lend);R_GE_linejoin GE_LJOINpar(SEXP value, int ind);SEXP GE_LJOINget(R_GE_linejoin ljoin);void GESetClip(double x1, double y1, double x2, double y2, pGEDevDesc dd);void GENewPage(const pGEcontext gc, pGEDevDesc dd);void GELine(double x1, double y1, double x2, double y2,const pGEcontext gc, pGEDevDesc dd);void GEPolyline(int n, double *x, double *y,const pGEcontext gc, pGEDevDesc dd);void GEPolygon(int n, double *x, double *y,const pGEcontext gc, pGEDevDesc dd);SEXP GEXspline(int n, double *x, double *y, double *s, Rboolean open,Rboolean repEnds, Rboolean draw,const pGEcontext gc, pGEDevDesc dd);void GECircle(double x, double y, double radius,const pGEcontext gc, pGEDevDesc dd);void GERect(double x0, double y0, double x1, double y1,const pGEcontext gc, pGEDevDesc dd);void GEPath(double *x, double *y,int npoly, int *nper,Rboolean winding,const pGEcontext gc, pGEDevDesc dd);void GERaster(unsigned int *raster, int w, int h,double x, double y, double width, double height,double angle, Rboolean interpolate,const pGEcontext gc, pGEDevDesc dd);SEXP GECap(pGEDevDesc dd);void GEText(double x, double y, const char * const str, cetype_t enc,double xc, double yc, double rot,const pGEcontext gc, pGEDevDesc dd);void GEMode(int mode, pGEDevDesc dd);void GESymbol(double x, double y, int pch, double size,const pGEcontext gc, pGEDevDesc dd);void GEPretty(double *lo, double *up, int *ndiv);void GEMetricInfo(int c, const pGEcontext gc,double *ascent, double *descent, double *width,pGEDevDesc dd);double GEStrWidth(const char *str, cetype_t enc,const pGEcontext gc, pGEDevDesc dd);double GEStrHeight(const char *str, cetype_t enc,const pGEcontext gc, pGEDevDesc dd);void GEStrMetric(const char *str, cetype_t enc, const pGEcontext gc,double *ascent, double *descent, double *width,pGEDevDesc dd);int GEstring_to_pch(SEXP pch);/*-------------------------------------------------------------------** LINE TEXTURE CODE is concerned with the internals of R* line texture representation.*/unsigned int GE_LTYpar(SEXP, int);SEXP GE_LTYget(unsigned int);/** Raster operations*/void R_GE_rasterScale(unsigned int *sraster, int sw, int sh,unsigned int *draster, int dw, int dh);void R_GE_rasterInterpolate(unsigned int *sraster, int sw, int sh,unsigned int *draster, int dw, int dh);void R_GE_rasterRotatedSize(int w, int h, double angle,int *wnew, int *hnew);void R_GE_rasterRotatedOffset(int w, int h, double angle, int botleft,double *xoff, double *yoff);void R_GE_rasterResizeForRotation(unsigned int *sraster,int w, int h,unsigned int *newRaster,int wnew, int hnew,const pGEcontext gc);void R_GE_rasterRotate(unsigned int *sraster, int w, int h, double angle,unsigned int *draster, const pGEcontext gc,Rboolean perPixelAlpha);/** From plotmath.c*/double GEExpressionWidth(SEXP expr,const pGEcontext gc, pGEDevDesc dd);double GEExpressionHeight(SEXP expr,const pGEcontext gc, pGEDevDesc dd);void GEExpressionMetric(SEXP expr, const pGEcontext gc,double *ascent, double *descent, double *width,pGEDevDesc dd);void GEMathText(double x, double y, SEXP expr,double xc, double yc, double rot,const pGEcontext gc, pGEDevDesc dd);/** (End from plotmath.c)*//** From plot3d.c : used in package clines*/SEXP GEcontourLines(double *x, int nx, double *y, int ny,double *z, double *levels, int nl);/** (End from plot3d.c)*//** From vfonts.c*/double R_GE_VStrWidth(const char *s, cetype_t enc, const pGEcontext gc, pGEDevDesc dd);double R_GE_VStrHeight(const char *s, cetype_t enc, const pGEcontext gc, pGEDevDesc dd);void R_GE_VText(double x, double y, const char * const s, cetype_t enc,double x_justify, double y_justify, double rotation,const pGEcontext gc, pGEDevDesc dd);/** (End from vfonts.c)*//* Also in Graphics.h */#define DEG2RAD 0.01745329251994329576pGEDevDesc GEcurrentDevice(void);Rboolean GEdeviceDirty(pGEDevDesc dd);void GEdirtyDevice(pGEDevDesc dd);Rboolean GEcheckState(pGEDevDesc dd);Rboolean GErecording(SEXP call, pGEDevDesc dd);void GErecordGraphicOperation(SEXP op, SEXP args, pGEDevDesc dd);void GEinitDisplayList(pGEDevDesc dd);void GEplayDisplayList(pGEDevDesc dd);void GEcopyDisplayList(int fromDevice);SEXP GEcreateSnapshot(pGEDevDesc dd);void GEplaySnapshot(SEXP snapshot, pGEDevDesc dd);void GEonExit(void);void GEnullDevice(void);/* From ../../main/plot.c, used by ../../library/grid/src/grid.c : */#define CreateAtVector Rf_CreateAtVectorSEXP CreateAtVector(double axp[], const double usr[], int nint, Rboolean logflag);/* From ../../main/graphics.c, used by ../../library/grDevices/src/axis_scales.c : */#define GAxisPars Rf_GAxisParsvoid GAxisPars(double *min, double *max, int *n, Rboolean log, int axis);/* Patterns - from ../../main/patterns.c */Rboolean R_GE_isPattern(SEXP x);#define R_GE_linearGradientPattern 1#define R_GE_radialGradientPattern 2#define R_GE_tilingPattern 3int R_GE_patternType(SEXP pattern);double R_GE_linearGradientX1(SEXP pattern);double R_GE_linearGradientY1(SEXP pattern);double R_GE_linearGradientX2(SEXP pattern);double R_GE_linearGradientY2(SEXP pattern);int R_GE_linearGradientNumStops(SEXP pattern);double R_GE_linearGradientStop(SEXP pattern, int i);rcolor R_GE_linearGradientColour(SEXP pattern, int i);/* Must match order in ../library/grDevices/R/patterns.R */#define R_GE_patternExtendPad 1#define R_GE_patternExtendRepeat 2#define R_GE_patternExtendReflect 3#define R_GE_patternExtendNone 4int R_GE_linearGradientExtend(SEXP pattern);double R_GE_radialGradientCX1(SEXP pattern);double R_GE_radialGradientCY1(SEXP pattern);double R_GE_radialGradientR1(SEXP pattern);double R_GE_radialGradientCX2(SEXP pattern);double R_GE_radialGradientCY2(SEXP pattern);double R_GE_radialGradientR2(SEXP pattern);int R_GE_radialGradientNumStops(SEXP pattern);double R_GE_radialGradientStop(SEXP pattern, int i);rcolor R_GE_radialGradientColour(SEXP pattern, int i);int R_GE_radialGradientExtend(SEXP pattern);SEXP R_GE_tilingPatternFunction(SEXP pattern);double R_GE_tilingPatternX(SEXP pattern);double R_GE_tilingPatternY(SEXP pattern);double R_GE_tilingPatternWidth(SEXP pattern);double R_GE_tilingPatternHeight(SEXP pattern);int R_GE_tilingPatternExtend(SEXP pattern);/* Composition operators *//* Must match order in ../library/grDevices/R/group.R *//* Porter-Duff */#define R_GE_compositeClear 1#define R_GE_compositeSource 2#define R_GE_compositeOver 3#define R_GE_compositeIn 4#define R_GE_compositeOut 5#define R_GE_compositeAtop 6#define R_GE_compositeDest 7#define R_GE_compositeDestOver 8#define R_GE_compositeDestIn 9#define R_GE_compositeDestOut 10#define R_GE_compositeDestAtop 11#define R_GE_compositeXor 12/* Additional Porter-Duff */#define R_GE_compositeAdd 13#define R_GE_compositeSaturate 14/* PDF Blend Modes */#define R_GE_compositeMultiply 15#define R_GE_compositeScreen 16#define R_GE_compositeOverlay 17#define R_GE_compositeDarken 18#define R_GE_compositeLighten 19#define R_GE_compositeColorDodge 20#define R_GE_compositeColorBurn 21#define R_GE_compositeHardLight 22#define R_GE_compositeSoftLight 23#define R_GE_compositeDifference 24#define R_GE_compositeExclusion 25/* Path rules *//* Must match order in ../library/grDevices/R/path.R */#define R_GE_nonZeroWindingRule 1#define R_GE_evenOddRule 2int R_GE_clipPathFillRule(SEXP path);void GEStroke(SEXP path, const pGEcontext gc, pGEDevDesc dd);void GEFill(SEXP path, int rule, const pGEcontext gc, pGEDevDesc dd);void GEFillStroke(SEXP path, int rule, const pGEcontext gc, pGEDevDesc dd);/* Mask types *//* Must match order in ../library/grDevices/R/mask.R */#define R_GE_alphaMask 1#define R_GE_luminanceMask 2int R_GE_maskType(SEXP mask);/* Device capabilities *//* Must match order in ../library/grDevices/R/device.R */#define R_GE_capability_semiTransparency 0#define R_GE_capability_transparentBackground 1#define R_GE_capability_rasterImage 2#define R_GE_capability_capture 3#define R_GE_capability_locator 4#define R_GE_capability_events 5#define R_GE_capability_patterns 6#define R_GE_capability_clippingPaths 7#define R_GE_capability_masks 8#define R_GE_capability_compositing 9#define R_GE_capability_transformations 10#define R_GE_capability_paths 11#define R_GE_capability_glyphs 12/* Must match order in ../library/grDevices/R/glyph.R */#define R_GE_text_style_normal 1#define R_GE_text_style_italic 2#define R_GE_text_style_oblique 3SEXP R_GE_glyphInfoGlyphs(SEXP glyphInfo);SEXP R_GE_glyphInfoFonts(SEXP glyphInfo);SEXP R_GE_glyphID(SEXP glyphs);SEXP R_GE_glyphX(SEXP glyphs);SEXP R_GE_glyphY(SEXP glyphs);SEXP R_GE_glyphFont(SEXP glyphs);SEXP R_GE_glyphSize(SEXP glyphs);SEXP R_GE_glyphColour(SEXP glyphs);const char* R_GE_glyphFontFile(SEXP glyphFont);int R_GE_glyphFontIndex(SEXP glyphFont);const char* R_GE_glyphFontFamily(SEXP glyphFont);double R_GE_glyphFontWeight(SEXP glyphFont);int R_GE_glyphFontStyle(SEXP glyphFont);const char* R_GE_glyphFontPSname(SEXP glyphFont);void GEGlyph(int n, int *glyphs, double *x, double *y,SEXP font, double size,int colour, double rot, pGEDevDesc dd);#ifdef __cplusplus}#endif#endif /* R_GRAPHICSENGINE_ */