X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9cc4ab8522ec1978be193ae11b71e5623d78a14d..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/graphics.h diff --git a/interface/wx/graphics.h b/interface/wx/graphics.h index f484162398..7425c4a78a 100644 --- a/interface/wx/graphics.h +++ b/interface/wx/graphics.h @@ -3,7 +3,7 @@ // Purpose: interface of various wxGraphics* classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -22,18 +22,24 @@ class wxGraphicsPath : public wxGraphicsObject { public: /** - Adds an arc of a circle centering at (@a x,@a y) with radius (@a r) - from @a startAngle to @a endAngle. + Adds an arc of a circle. + + The circle is defined by the coordinates of its centre (@a x, @a y) or + @a c and its radius @a r. The arc goes from the starting angle @a + startAngle to @a endAngle either clockwise or counter-clockwise + depending on the value of @a clockwise argument. + + The angles are measured in radians but, contrary to the usual + mathematical convention, are always @e clockwise from the horizontal + axis. */ + //@{ virtual void AddArc(wxDouble x, wxDouble y, wxDouble r, wxDouble startAngle, wxDouble endAngle, bool clockwise); - /** - Adds an arc of a circle centering at @a c with radius (@a r) - from @a startAngle to @a endAngle. - */ void AddArc(const wxPoint2DDouble& c, wxDouble r, wxDouble startAngle, wxDouble endAngle, bool clockwise); + //@} /** Appends a an arc to two tangents connecting (current) to (@a x1,@a y1) @@ -194,6 +200,70 @@ public: bool IsNull() const; }; +/** + Anti-aliasing modes used by wxGraphicsContext::SetAntialiasMode(). +*/ +enum wxAntialiasMode +{ + /** No anti-aliasing */ + wxANTIALIAS_NONE, + + /** The default anti-aliasing */ + wxANTIALIAS_DEFAULT, +}; + +/** + Interpolation quality used by wxGraphicsContext::SetInterpolationQuality(). + */ +enum wxInterpolationQuality +{ + /** default interpolation, based on type of context, in general medium quality */ + wxINTERPOLATION_DEFAULT, + /** no interpolation */ + wxINTERPOLATION_NONE, + /** fast interpolation, suited for interactivity */ + wxINTERPOLATION_FAST, + /** better quality */ + wxINTERPOLATION_GOOD, + /** best quality, not suited for interactivity */ + wxINTERPOLATION_BEST +}; + +/** + Compositing is done using Porter-Duff compositions + (see http://keithp.com/~keithp/porterduff/p253-porter.pdf) with + wxGraphicsContext::SetCompositionMode(). + + The description give a short equation on how the values of a resulting + pixel are calculated. + @e R = Result, @e S = Source, @e D = Destination, colors premultiplied with alpha + @e Ra, @e Sa, @e Da their alpha components +*/ +enum wxCompositionMode +{ + /** + Indicates invalid or unsupported composition mode. + + This value can't be passed to wxGraphicsContext::SetCompositionMode(). + + @since 2.9.2 + */ + wxCOMPOSITION_INVALID = -1, + wxCOMPOSITION_CLEAR, /**< @e R = 0 */ + wxCOMPOSITION_SOURCE, /**< @e R = S */ + wxCOMPOSITION_OVER, /**< @e R = @e S + @e D*(1 - @e Sa) */ + wxCOMPOSITION_IN, /**< @e R = @e S*@e Da */ + wxCOMPOSITION_OUT, /**< @e R = @e S*(1 - @e Da) */ + wxCOMPOSITION_ATOP, /**< @e R = @e S*@e Da + @e D*(1 - @e Sa) */ + + wxCOMPOSITION_DEST, /**< @e R = @e D, essentially a noop */ + wxCOMPOSITION_DEST_OVER, /**< @e R = @e S*(1 - @e Da) + @e D */ + wxCOMPOSITION_DEST_IN, /**< @e R = @e D*@e Sa */ + wxCOMPOSITION_DEST_OUT, /**< @e R = @e D*(1 - @e Sa) */ + wxCOMPOSITION_DEST_ATOP, /**< @e R = @e S*(1 - @e Da) + @e D*@e Sa */ + wxCOMPOSITION_XOR, /**< @e R = @e S*(1 - @e Da) + @e D*(1 - @e Sa) */ + wxCOMPOSITION_ADD /**< @e R = @e S + @e D */ +}; /** @@ -272,6 +342,16 @@ public: */ static wxGraphicsContext* Create(const wxPrinterDC& dc); + /** + Creates a wxGraphicsContext from a wxEnhMetaFileDC. + + This function, as wxEnhMetaFileDC class itself, is only available only + under MSW. + + @see wxGraphicsRenderer::CreateContext() + */ + static wxGraphicsContext* Create(const wxEnhMetaFileDC& dc); + /** Clips drawings to the specified region. */ @@ -316,15 +396,25 @@ public: static wxGraphicsContext* CreateFromNativeWindow(void* window); /** - Creates a native brush, having a linear gradient, starting at - (@a x1, @a y1) with color @a c1 to (@a x2, @a y2) with color @a c2. + Creates a native brush with a linear gradient. + + The brush starts at (@a x1, @a y1) and ends at (@a x2, @a y2). Either + just the start and end gradient colours (@a c1 and @a c2) or full set + of gradient @a stops can be specified. + + The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1. */ - virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, - wxDouble y1, - wxDouble x2, - wxDouble y2, - const wxColour& c1, - const wxColour& c2) const; + //@{ + wxGraphicsBrush + CreateLinearGradientBrush(wxDouble x1, wxDouble y1, + wxDouble x2, wxDouble y2, + const wxColour& c1, const wxColour& c2) const; + + wxGraphicsBrush + CreateLinearGradientBrush(wxDouble x1, wxDouble y1, + wxDouble x2, wxDouble y2, + const wxGraphicsGradientStops& stops) const; + //@} /** Creates a native affine transformation matrix from the passed in @@ -346,15 +436,30 @@ public: virtual wxGraphicsPen CreatePen(const wxPen& pen) const; /** - Creates a native brush, having a radial gradient originating at - (@a xo, @a yc) with color @a oColour and ends on a circle around - (@a xc, @a yc) with the given @a radius and color @a cColour. + Creates a native brush with a radial gradient. + + The brush originates at (@a xo, @a yc) and ends on a circle around + (@a xc, @a yc) with the given @a radius. + + The gradient may be specified either by its start and end colours @a + oColor and @a cColor or by a full set of gradient @a stops. + + The version taking wxGraphicsGradientStops is new in wxWidgets 2.9.1. */ - virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo, - wxDouble xc, wxDouble yc, - wxDouble radius, - const wxColour& oColor, - const wxColour& cColor) const; + //@{ + virtual wxGraphicsBrush + CreateRadialGradientBrush(wxDouble xo, wxDouble yo, + wxDouble xc, wxDouble yc, + wxDouble radius, + const wxColour& oColor, + const wxColour& cColor) const; + + virtual wxGraphicsBrush + CreateRadialGradientBrush(wxDouble xo, wxDouble yo, + wxDouble xc, wxDouble yc, + wxDouble radius, + const wxGraphicsGradientStops& stops) = 0; + //@} /** Draws the bitmap. In case of a mono bitmap, this is treated as a mask @@ -378,13 +483,13 @@ public: Draws a polygon. */ virtual void DrawLines(size_t n, const wxPoint2DDouble* points, - int fillStyle = wxODDEVEN_RULE); + wxPolygonFillMode fillStyle = wxODDEVEN_RULE); /** Draws the path by first filling and then stroking. */ virtual void DrawPath(const wxGraphicsPath& path, - int fillStyle = wxODDEVEN_RULE); + wxPolygonFillMode fillStyle = wxODDEVEN_RULE); /** Draws a rectangle. @@ -404,6 +509,12 @@ public: /** Draws text at the defined position. + @param str + The text to draw. + @param x + The x coordinate position to draw the text at. + @param y + The y coordinate position to draw the text at. @param angle The angle relative to the (default) horizontal direction to draw the string. @@ -412,6 +523,12 @@ public: /** Draws text at the defined position. + @param str + The text to draw. + @param x + The x coordinate position to draw the text at. + @param y + The y coordinate position to draw the text at. @param backgroundBrush Brush to fill the text with. */ @@ -420,6 +537,12 @@ public: /** Draws text at the defined position. + @param str + The text to draw. + @param x + The x coordinate position to draw the text at. + @param y + The y coordinate position to draw the text at. @param angle The angle relative to the (default) horizontal direction to draw the string. @@ -433,7 +556,7 @@ public: Fills the path with the current brush. */ virtual void FillPath(const wxGraphicsPath& path, - int fillStyle = wxODDEVEN_RULE) = 0; + wxPolygonFillMode fillStyle = wxODDEVEN_RULE) = 0; /** Returns the native context (CGContextRef for Core Graphics, Graphics @@ -495,7 +618,7 @@ public: /** Sets the brush for filling paths. */ - void SetBrush(const wxGraphicsBrush& brush); + virtual void SetBrush(const wxGraphicsBrush& brush); /** Sets the font for drawing text. @@ -504,16 +627,16 @@ public: /** Sets the font for drawing text. */ - void SetFont(const wxGraphicsFont& font); + virtual void SetFont(const wxGraphicsFont& font); /** Sets the pen used for stroking. */ - void SetPen(const wxGraphicsPen& pen); + void SetPen(const wxPen& pen); /** Sets the pen used for stroking. */ - void SetPen(const wxPen& pen); + virtual void SetPen(const wxGraphicsPen& pen); /** Sets the current transformation matrix of this context @@ -529,13 +652,15 @@ public: Stroke disconnected lines from begin to end points, fastest method available for this purpose. */ - void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints, - const wxPoint2DDouble* endPoints); + virtual void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints, + const wxPoint2DDouble* endPoints); /** - Stroke disconnected lines from begin to end points, fastest method - available for this purpose. + Stroke lines connecting all the points. + + Unlike the other overload of this function, this method draws a single + polyline and not a number of disconnected lines. */ - void StrokeLines(size_t n, const wxPoint2DDouble* points); + virtual void StrokeLines(size_t n, const wxPoint2DDouble* points); /** Strokes along a path with the current pen. @@ -546,9 +671,162 @@ public: Translates the current transformation matrix. */ virtual void Translate(wxDouble dx, wxDouble dy) = 0; + + /** + Redirects all rendering is done into a fully transparent temporary context + */ + virtual void BeginLayer(wxDouble opacity) = 0; + + /** + Composites back the drawings into the context with the opacity given at + the BeginLayer call + */ + virtual void EndLayer() = 0; + + /** + Sets the antialiasing mode, returns true if it supported + */ + virtual bool SetAntialiasMode(wxAntialiasMode antialias) = 0; + + /** + Returns the current shape antialiasing mode + */ + virtual wxAntialiasMode GetAntialiasMode() const ; + + /** + Sets the interpolation quality, returns true if it supported + */ + virtual bool SetInterpolationQuality(wxInterpolationQuality interpolation) = 0; + + /** + Returns the current interpolation quality + */ + virtual wxInterpolationQuality GetInterpolationQuality() const; + + /** + Sets the compositing operator, returns true if it supported + */ + virtual bool SetCompositionMode(wxCompositionMode op) = 0; + + /** + Returns the current compositing operator + */ + virtual wxCompositionMode GetCompositionMode() const; + }; +/** + Represents a single gradient stop in a collection of gradient stops as + represented by wxGraphicsGradientStops. + @library{wxcore} + @category{gdi} + + @since 2.9.1 +*/ +class wxGraphicsGradientStop +{ +public: + /** + Creates a stop with the given colour and position. + + @param col The colour of this stop. Note that the alpha component of + the colour is honoured thus allowing the background colours to + partially show through the gradient. + @param pos The stop position, must be in [0, 1] range with 0 being the + beginning and 1 the end of the gradient. + */ + wxGraphicsGradientStop(wxColour col = wxTransparentColour, float pos = 0.); + + /// Return the stop colour. + const wxColour& GetColour() const; + + /** + Change the stop colour. + + @param col The new colour. + */ + void SetColour(const wxColour& col); + + /// Return the stop position. + float GetPosition() const; + + /** + Change the stop position. + + @param pos The new position, must always be in [0, 1] range. + */ + void SetPosition(float pos); +}; + +/** + Represents a collection of wxGraphicGradientStop values for use with + CreateLinearGradientBrush and CreateRadialGradientBrush. + + The stops are maintained in order of position. If two or more stops are + added with the same position then the one(s) added later come later. + This can be useful for producing discontinuities in the colour gradient. + + Notice that this class is write-once, you can't modify the stops once they + had been added. + + @library{wxcore} + @category{gdi} + + @since 2.9.1 +*/ +class wxGraphicsGradientStops +{ +public: + /** + Initializes the gradient stops with the given boundary colours. + + Creates a wxGraphicsGradientStops instance with start colour given + by @a startCol and end colour given by @a endCol. + */ + wxGraphicsGradientStops(wxColour startCol = wxTransparentColour, + wxColour endCol = wxTransparentColour); + + /** + Add a new stop. + */ + //@{ + void Add(const wxGraphicsGradientStop& stop); + void Add(wxColour col, float pos); + //@} + + /** + Returns the stop at the given index. + + @param n The index, must be in [0, GetCount()) range. + */ + wxGraphicsGradientStop Item(unsigned n) const; + + /** + Returns the number of stops. + */ + unsigned GetCount() const; + + /** + Set the start colour to @a col + */ + void SetStartColour(wxColour col); + + /** + Returns the start colour. + */ + wxColour GetStartColour() const; + + /** + Set the end colour to @a col + */ + void SetEndColour(wxColour col); + + /** + Returns the end colour. + */ + wxColour GetEndColour() const; +}; /** @class wxGraphicsRenderer @@ -594,6 +872,14 @@ public: */ virtual wxGraphicsContext* CreateContext(const wxPrinterDC& dc) = 0 ; + /** + Creates a wxGraphicsContext from a wxEnhMetaFileDC. + + This function, as wxEnhMetaFileDC class itself, is only available only + under MSW. + */ + virtual wxGraphicsContext* CreateContext(const wxEnhMetaFileDC& dc) = 0; + /** Creates a native brush from a wxBrush. */ @@ -611,22 +897,30 @@ public: */ virtual wxGraphicsContext* CreateContextFromNativeWindow(void* window) = 0; + /** + Creates a wxGraphicsContext that can be used for measuring texts only. + No drawing commands are allowed. + */ + virtual wxGraphicsContext * CreateMeasuringContext() = 0; + /** Creates a native graphics font from a wxFont and a text colour. */ virtual wxGraphicsFont CreateFont(const wxFont& font, const wxColour& col = *wxBLACK) = 0; + /** - Creates a native brush, having a linear gradient, starting at - (@a x1, @a y1) with color @a c1 to (@a x2, @a y2) with color @a c2. + Creates a native brush with a linear gradient. + + Stops support is new since wxWidgets 2.9.1, previously only the start + and end colours could be specified. */ virtual wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, wxDouble y1, wxDouble x2, wxDouble y2, - const wxColour& c1, - const wxColour& c2) = 0; + const wxGraphicsGradientStops& stops) = 0; /** Creates a native affine transformation matrix from the passed in @@ -648,15 +942,15 @@ public: virtual wxGraphicsPen CreatePen(const wxPen& pen) = 0; /** - Creates a native brush, having a radial gradient originating at - (@a xo, @a yc) with color @a oColour and ends on a circle around - (@a xc, @a yc) with the given @a radius and color @a cColour. + Creates a native brush with a radial gradient. + + Stops support is new since wxWidgets 2.9.1, previously only the start + and end colours could be specified. */ virtual wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, wxDouble yo, wxDouble xc, wxDouble yc, wxDouble radius, - const wxColour& oColour, - const wxColour& cColour) = 0; + const wxGraphicsGradientStops& stops) = 0; /** Returns the default renderer on this platform. On OS X this is the Core