From 12799e17d55c09d322bc49bfd9f1247c03f3c0b2 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Fri, 28 Jul 2017 15:18:29 -0400 Subject: bookmaker generated site docs The documents were generated by running tools/bookmaker against docs/*.bmh No-Try: true Docs-Preview: https://skia.org/?cl=28002 Change-Id: I7d7dd73cdea4a234c6175646d5b8938e1af3117a Reviewed-on: https://skia-review.googlesource.com/28002 Reviewed-by: Cary Clark Commit-Queue: Cary Clark --- site/user/api/METADATA | 2 +- site/user/api/SkCanvas_Reference.md | 4911 +++++++++++++++++++++++++++++++++ site/user/api/SkPaint_Reference.md | 5190 +++++++++++++++++++++++++++++++++++ site/user/api/SkPath_Reference.md | 4975 +++++++++++++++++++++++++++++++++ site/user/api/canvas.md | 264 -- site/user/api/creating_skcanvas.md | 264 ++ site/user/api/index.md | 15 +- site/user/api/skcanvas.md | 70 - site/user/api/skcanvas_overivew.md | 70 + site/user/api/skmatrix.md | 12 - site/user/api/skmatrix_overivew.md | 12 + site/user/api/skpaint.md | 207 -- site/user/api/skpaint_overview.md | 207 ++ site/user/api/skrect.md | 73 - site/user/api/skrect_overivew.md | 73 + site/user/api/skregion.md | 111 - site/user/api/skregion_overview.md | 111 + site/user/api/undocumented.md | 638 +++++ site/user/api/usingBookmaker.md | 79 + 19 files changed, 16540 insertions(+), 744 deletions(-) create mode 100644 site/user/api/SkCanvas_Reference.md create mode 100644 site/user/api/SkPaint_Reference.md create mode 100644 site/user/api/SkPath_Reference.md delete mode 100644 site/user/api/canvas.md create mode 100644 site/user/api/creating_skcanvas.md delete mode 100644 site/user/api/skcanvas.md create mode 100644 site/user/api/skcanvas_overivew.md delete mode 100644 site/user/api/skmatrix.md create mode 100644 site/user/api/skmatrix_overivew.md delete mode 100644 site/user/api/skpaint.md create mode 100644 site/user/api/skpaint_overview.md delete mode 100644 site/user/api/skrect.md create mode 100644 site/user/api/skrect_overivew.md delete mode 100644 site/user/api/skregion.md create mode 100644 site/user/api/skregion_overview.md create mode 100644 site/user/api/undocumented.md create mode 100644 site/user/api/usingBookmaker.md (limited to 'site/user') diff --git a/site/user/api/METADATA b/site/user/api/METADATA index 27625c5c1a..83df9430d8 100644 --- a/site/user/api/METADATA +++ b/site/user/api/METADATA @@ -1,3 +1,3 @@ { - "fileOrder": ["skcanvas", "skpaint", "skrect", "skregion", "skmatrix", "grcontext", "canvas"] + "fileOrder": ["skcanvas_overview", "skpaint_overview", "skrect_overview", "skregion_overview", "skmatrix_overview", "creating_skcanvas", "SkCanvas_Reference", "SkPaint_Reference", "SkPath_Reference", "usingBookmaker"] } diff --git a/site/user/api/SkCanvas_Reference.md b/site/user/api/SkCanvas_Reference.md new file mode 100644 index 0000000000..f6976b2750 --- /dev/null +++ b/site/user/api/SkCanvas_Reference.md @@ -0,0 +1,4911 @@ +SkCanvas Reference +=== + +# Canvas +Canvas provides an interface for drawing, and how the drawing is clipped and transformed. +Canvas contains a stack of Matrix and Clip values. + +Canvas and Paint together provide the state to draw into Surface or Device. +Each Canvas draw call transforms the geometry of the object by the concatenation of all Matrix +values in the stack. +The transformed geometry is clipped by the intersection of all of Clip values in the stack. +The Canvas draw calls take Paint parameter for drawing state. +Create Paint to supply the drawing state, such as Color, +Typeface, Paint Text Size, Paint Stroke Width, Shader and so on. + +To draw to a pixel-based destination, create Raster Surface or GPU Surface. +Request Canvas from Surface to obtain the interface to draw. +Canvas generated by Raster Surface draws to memory visible to the CPU. +Canvas generated by GPU Surface uses Vulkan or OpenGL to draw to the GPU. + +Canvas can be constructed to draw to Bitmap without first creating Raster Surface. +This approach may be deprecated in the future. + +To draw to a document, obtain Canvas from SVG Canvas, Document PDF, or Picture Recorder. +Document-based Canvas and other Canvas subclasses reference Device describing the destination. + +# Class SkCanvas + +# Overview + +## Subtopics + +| topics | description | +| --- | --- | + +## Constants + +| constants | description | +| --- | --- | +| Lattice::Flags | Controls Lattice transparency. | +| PointMode | Sets drawPoints options. | +| SaveLayerFlags | Sets SaveLayerRec options. | +| SrcRectConstraint | Sets drawImageRect options. | + +## Structs + +| struct | description | +| --- | --- | +| Lattice | Divides Bitmap, Image into a rectangular grid. | +| SaveLayerRec | Contains state to create the layer offscreen. | + +## Constructors + +Create the desired type of Surface to obtain its Canvas when possible. Constructors are useful +when no Surface is required, and some helpers implicitly create Raster Surface. + +| | description | +| --- | --- | +| SkCanvas() | No Surface, no dimensions. | +| | No Surface, set dimensions, Surface Properties. | +| SkCanvas(SkBaseDevice* device) | Existing Device. (SkBaseDevice is private.) | +| SkCanvas(const SkBitmap& bitmap) | Uses existing Bitmap. | +| SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props) | Uses existing Bitmap and Surface Properties. | +| MakeRasterDirect | Creates from SkImageInfo and Pixel Storage. | +| MakeRasterDirectN32 | Creates from image data and Pixel Storage. | + +## Member Functions + +| function | description | +| --- | --- | +| accessTopLayerPixels | Returns writable pixel access if available. | +| accessTopRasterHandle | Returns context that tracks Clip and Matrix. | +| clear | Fills Clip with Color. | +| clipPath | Combines Clip with Path. | +| clipRRect | Combines Clip with Round Rect. | +| clipRect | Combines Clip with Rect. | +| clipRegion | Combines Clip with Region. | +| concat | Multiplies Matrix by Matrix. | +| discard | Makes Canvas contents undefined. | +| drawAnnotation | Associates a Rect with a key-value pair. | +| drawArc | Draws Arc using Clip, Matrix, and Paint. | +| drawAtlas | Draws sprites using Clip, Matrix, and Paint. | +| drawBitmap | Draws Bitmap at (x, y) position. | +| drawBitmapLattice | Draws differentially stretched Bitmap. | +| drawBitmapNine | Draws Nine Patch Bitmap. | +| drawBitmapRect | Draws Bitmap, source Rect to destination Rect. | +| drawCircle | Draws Circle using Clip, Matrix, and Paint. | +| drawColor | Fills Clip with Color and Blend Mode. | +| drawDRRect | Draws double Round Rect stroked or filled. | +| drawDrawable | Draws Drawable, encapsulated drawing commands. | +| drawIRect | Draws IRect using Clip, Matrix, and Paint. | +| drawImage | Draws Image at (x, y) position. | +| drawImageLattice | Draws differentially stretched Image. | +| drawImageNine | Draws Nine Patch Image. | +| drawImageRect | Draws Image, source Rect to destination Rect. | +| drawLine | Draws line segment between two points. | +| drawOval | Draws Oval using Clip, Matrix, and Paint. | +| drawPaint | Fills Clip with Paint. | +| drawPatch | Draws cubic Coons patch. | +| drawPath | Draws Path using Clip, Matrix, and Paint. | +| drawPicture | Draws Picture using Clip and Matrix. | +| drawPoint | Draws point at (x, y) position. | +| drawPoints | Draws array as points, lines, polygon. | +| drawPosText | Draws text at array of (x, y) positions. | +| drawPosTextH | Draws text at x positions with common baseline. | +| drawRRect | Draws Round Rect using Clip, Matrix, and Paint. | +| drawRect | Draws Rect using Clip, Matrix, and Paint. | +| drawRegion | Draws Region using Clip, Matrix, and Paint. | +| drawRoundRect | Draws Round Rect using Clip, Matrix, and Paint. | +| drawText | Draws text at (x, y), using font advance. | +| drawTextBlob | Draws text with arrays of positions and Paint. | +| drawTextOnPath | Draws text following Path contour. | +| drawTextOnPathHV | Draws text following Path with offsets. | +| drawTextRSXform | Draws text with array of RSXform. | +| drawString | Draws null terminated string at (x, y) using font advance. | +| drawVertices | Draws Vertices, a triangle mesh. | +| flush | Triggers execution of all pending draw operations. | +| getBaseLayerSize | Gets size of base layer in global coordinates. | +| getDeviceClipBounds | Returns IRect bounds of Clip. | +| getDrawFilter | Legacy; to be deprecated. | +| getGrContext | Returns GPU Context of the GPU Surface. | +| getLocalClipBounds | Returns Clip bounds in source coordinates. | +| getMetaData | Associates additional data with the canvas. | +| getProps | Copies Surface Properties if available. | +| getSaveCount | Returns depth of stack containing Clip and Matrix. | +| getTotalMatrix | Returns Matrix. | +| imageInfo | Returns Image Info for Canvas. | +| isClipEmpty | Returns if Clip is empty. | +| isClipRect | Returns if Clip is Rect and not empty. | +| MakeRasterDirect | Creates Canvas from SkImageInfo and pixel data. | +| MakeRasterDirectN32 | Creates Canvas from image specifications and pixel data. | +| makeSurface | Creates Surface matching SkImageInfo and SkSurfaceProps. | +| peekPixels | Returns if Canvas has direct access to its pixels. | +| quickReject | Returns if Rect is outside Clip. | +| readPixels | Copies and converts rectangle of pixels from Canvas. | +| resetMatrix | Resets Matrix to identity. | +| restore | Restores changes to Clip and Matrix, pops save stack. | +| restoreToCount | Restores changes to Clip and Matrix to given depth. | +| rotate | Rotates Matrix. | +| save | Saves Clip and Matrix on stack. | +| saveLayer | Saves Clip and Matrix on stack; creates offscreen. | +| saveLayerAlpha | Saves Clip and Matrix on stack; creates offscreen; sets opacity. | +| saveLayerPreserveLCDTextRequests | Saves Clip and Matrix on stack; creates offscreen for LCD text. | +| scale | Scales Matrix. | +| setAllowSimplifyClip | Experimental. | +| setDrawFilter | Legacy; to be deprecated. | +| setMatrix | Sets Matrix. | +| skew | Skews Matrix. | +| translate | Translates Matrix. | +| writePixels | Copies and converts rectangle of pixels to Canvas. | + + +## MakeRasterDirect + +
+static std::unique_ptr MakeRasterDirect(const SkImageInfo& info,
+                                                  void* pixels, size_t rowBytes)
+
+ +Allocates raster canvas that will draw directly into pixels. +To access pixels after drawing, call flush or peekPixels. + +### Parameters + + + + + +
info +Width, height, Image Color Type, Image Alpha Type, Color Space, of Raster Surface. +Width, or height, or both, may be zero.
pixels +Pointer to destination pixels buffer. Buffer size should be info height +times rowBytes times bytes required for Image Color Type.
rowBytes +The interval from one Surface row to the next; equal to or greater than +info width times bytes required for Image Color Type.
+ +### Return Value + +Canvas if all parameters are valid; otherwise, nullptr. +Valid parameters include: info dimensions must be zero or positive, and other checks; +info must contain Image Color Type and Image Alpha Type supported by Raster Surface; +pixels must be not be nullptr; +rowBytes must be zero or large enough to contain width pixels of Image Color Type. + +### Example + +
Allocates a three by three bitmap, clears it to white, and draws a black pixel +in the center.
+ +#### Example Output + +~~~~ +--- +-x- +--- +~~~~ + +
+ +### See Also + +MakeRasterDirectN32 SkSurface::MakeRasterDirect + +--- + + +## MakeRasterDirectN32 + +
+static std::unique_ptr MakeRasterDirectN32(int width, int height,
+                                                     SkPMColor* pixels,
+                                                     size_t rowBytes)
+
+ +Creates Canvas with Raster Surface with inline image specification that draws into pixels. +Image Color Type is set to kN32 SkColorType. +Image Alpha Type is set to kPremul SkAlphaType. +To access pixels after drawing, call flush or peekPixels. + +### Parameters + + + + + + +
width +Pixel column count on Raster Surface created. Must be zero or greater.
height +Pixel row count on Raster Surface created. Must be zero or greater.
pixels +Pointer to destination pixels buffer. Buffer size should be height +times rowBytes times four.
rowBytes +The interval from one Surface row to the next; equal to or greater than +width times four.
+ +### Return Value + +Canvas if all parameters are valid; otherwise, nullptr. +Valid parameters include: width and height must be zero or positive; +pixels must be not be nullptr; +rowBytes must be zero or large enough to contain width pixels of Image Color Type. + +### Example + +
Allocates a three by three bitmap, clears it to white, and draws a black pixel +in the center.
+ +#### Example Output + +~~~~ +--- +-x- +--- +~~~~ + +
+ +--- + + +## SkCanvas + +
+SkCanvas()
+
+ +Creates an empty canvas with no backing device/pixels, and zero +dimensions. + +### Return Value + +An empty canvas. + +### Example + +
Passes a placeholder to a function that requires one.
+ +#### Example Output + +~~~~ +paint draws text left to right +paint draws text top to bottom +paint draws text top to bottom +~~~~ + +
+ +--- + + +## SkCanvas + +
+SkCanvas(int width, int height, const SkSurfaceProps* props = NULL)
+
+ +Creates Canvas of the specified dimensions without a Surface. +Used by subclasses with custom implementations for draw methods. + +### Parameters + + + + + +
width +Zero or greater.
height +Zero or greater.
props +The LCD striping orientation and setting for device independent fonts.
+ +### Return Value + +Canvas placeholder with dimensions. + +### Example + +
+ +#### Example Output + +~~~~ +canvas is empty +~~~~ + +
+ +--- + + +## SkCanvas + +
+explicit SkCanvas(SkBaseDevice* device)
+
+ +Construct a canvas that draws into device. +Used by child classes of SkCanvas. + +### Parameters + + + +
device +Specifies a device for the canvas to draw into.
+ +### Return Value + +Canvas that can be used to draw into device. + +### Example + +
+ +--- + + +## SkCanvas + +
+explicit SkCanvas(const SkBitmap& bitmap)
+
+ +Construct a canvas that draws into bitmap. +Sets SkSurfaceProps::kLegacyFontHost InitType in constructed Surface. + +### Parameters + + + +
bitmap +Width, height, Image Color Type, Image Alpha Type, and pixel storage of Raster Surface. +Bitmap is copied so that subsequently editing bitmap will not affect +constructed Canvas.
+ +### Return Value + +Canvas that can be used to draw into bitmap. + +### Example + +
The actual output depends on the installed fonts.
+ +#### Example Output + +~~~~ +----- +--x-- +--x-- +--x-- +--x-- +--x-- +--x-- +----- +--x-- +--x-- +----- +~~~~ + +
+ +--- + +## Enum SkCanvas::ColorBehavior + +
+enum class ColorBehavior {
+kLegacy,
+};
+ +### Constants + + + + + + +
SkCanvas::kLegacy 0
+ + +## SkCanvas + +
+SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props)
+
+ +Construct a canvas that draws into bitmap. +Use props to match the device characteristics, like LCD striping. + +### Parameters + + + + +
bitmap +Width, height, Image Color Type, Image Alpha Type, and pixel storage of Raster Surface. +Bitmap is copied so that subsequently editing bitmap will not affect +constructed Canvas.
props +The order and orientation of RGB striping; and whether to use +device independent fonts.
+ +### Return Value + +Canvas that can be used to draw into bitmap. + +### Example + +
The actual output depends on the installed fonts.
+ +#### Example Output + +~~~~ +----- +---x- +---x- +---x- +---x- +---x- +---x- +----- +---x- +---x- +----- +~~~~ + +
+ +--- + + +## ~SkCanvas + +
+virtual ~SkCanvas()
+
+ +Draws State Stack Layer, if any. +Free up resources used by Canvas. + +### Example + +
+ +--- + + +## getMetaData + +
+SkMetaData& getMetaData()
+
+ +Associates additional data with the canvas. +The storage is freed when Canvas is deleted. + +### Return Value + +storage that can be read from and written to. + +### Example + +
+ +#### Example Output + +~~~~ +before: (null) +during: Hello! +after: (null) +~~~~ + +
+ +--- + + +## imageInfo + +
+SkImageInfo imageInfo() const
+
+ +Returns Image Info for Canvas. If Canvas is not associated with Raster Surface or +GPU Surface, returns SkImageInfo::SkImageInfo() is returned Image Color Type is set to kUnknown SkColorType. + +### Return Value + +dimensions and Image Color Type of Canvas. + +### Example + +
+ +--- + + +## getProps + +
+bool getProps(SkSurfaceProps* props) const
+
+ +If Canvas is associated with Raster Surface or +GPU Surface, copies Surface Properties and returns true. Otherwise, +return false and leave props unchanged. + +### Parameters + + + +
props +Pointer to writable SkSurfaceProps.
+ +### Return Value + +true if Surface Properties was copied. + +### Example + +
+ +#### Example Output + +~~~~ +isRGB:0 +isRGB:1 +~~~~ + +
+ +--- + + +## flush + +
+void flush()
+
+ +Triggers the immediate execution of all pending draw operations. +If Canvas is associated with GPU Surface, resolve all pending GPU operations. + +### Example + +
+ +--- + + +## getBaseLayerSize + +
+virtual SkISize getBaseLayerSize() const
+
+ +Gets the size of the base or root layer in global canvas coordinates. The +origin of the base layer is always (0,0). The current drawable area may be +smaller (due to clipping or saveLayer). + +### Return Value + +Integral width and height of base layer. + +### Example + +
+ +#### Example Output + +~~~~ +clip=10,30 +size=20,30 +~~~~ + +
+ +--- + + +## makeSurface + +
+sk_sp makeSurface(const SkImageInfo& info,
+                             const SkSurfaceProps* props = nullptr)
+
+ +Creates Surface matching info and props, and associates it with Canvas. +If Canvas is already associated with Surface, it cannot create a new Surface. + +### Parameters + + + + +
info +Initialize Surface with width, height, Image Color Type, Image Alpha Type, and Color Space.
props +Use to match if provided, or use the Surface Properties in Canvas otherwise.
+ +### Return Value + +Surface matching info and props, or nullptr if no match is available. + +### Example + +
+ +#### Example Output + +~~~~ +compatible != nullptr +size = 3, 4 +~~~~ + +
+ +--- + + +## getGrContext + +
+virtual GrContext* getGrContext()
+
+ +Returns GPU Context of the GPU Surface associated with Canvas. + +### Return Value + +GPU Context, if available; nullptr otherwise. + +### Example + +
+ +--- + + +## accessTopLayerPixels + +
+void* accessTopLayerPixels(SkImageInfo* info, size_t* rowBytes,
+                           SkIPoint* origin = NULL)
+
+ +Returns the pixel base address, Image Info, rowBytes, and origin if the pixels +can be read directly. +The returned address is only valid +while Canvas is in scope and unchanged. Any Canvas call or Surface call +may invalidate the returned address and other returned values. + +If pixels are inaccessible, info, rowBytes, and origin are unchanged. + +### Parameters + + + + + +
info +If not nullptr, copies writable pixels' Image Info.
rowBytes +If not nullptr, copies writable pixels' row bytes.
origin +If not nullptr, copies Canvas top layer origin, its top left corner.
+ +### Return Value + +Address of pixels, or nullptr if inaccessible. + +### Example + +
+ +### Example + +
Draws "" on the device. Then draws "" in an offscreen layer, and reads the +offscreen to add a large dotted "". Finally blends the offscreen with the +device. + +The offscreen and blended result appear on the CPU and GPU but the large dotted +"" appear only on the CPU.
+ +--- + + +## accessTopRasterHandle + +
+SkRasterHandleAllocator::Handle accessTopRasterHandle() const
+
+ +Returns custom context that tracks the Matrix and Clip. + +Use Raster Handle Allocator to blend Skia drawing with custom drawing, typically performed +by the host platform's user interface. This accessor returns the custom context created +when SkRasterHandleAllocator::MakeCanvas creates a custom canvas with raster storage for +the drawing destination. + +### Return Value + +Context of custom allocator. + +### Example + +
+ +#### Example Output + +~~~~ +context = skia +~~~~ + +
+ +### See Also + +SkRasterHandleAllocator + +--- + + +## peekPixels + +
+bool peekPixels(SkPixmap* pixmap)
+
+ +Returns true if Canvas has direct access to its pixels. + +Pixels are readable when Device is raster. Pixels are not readable when SkCanvas is returned from +GPU Surface, returned by SkDocument::beginPage, returned by SkPictureRecorder::beginRecording, +or SkCanvas is the base of a utility class like SkDumpCanvas. + +pixmap pixel address is only valid while Canvas is in scope and unchanged. Any Canvas or Surface call may +invalidate the pixmap values. + +### Parameters + + + +
pixmap +storage for Canvas pixel state if Canvas pixels are readable; otherwise, ignored.
+ +### Return Value + +true if Canvas has direct access to pixels. + +### Example + +
+ +#### Example Output + +~~~~ +width=256 height=256 +~~~~ + +
+ +--- + + +## readPixels + +
+bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
+                int srcX, int srcY)
+
+ +Copies rectangle of pixels from Canvas into dstPixels, converting their Image Color Type and Image Alpha Type. +Pixels are readable when Device is raster. Pixels are not readable when SkCanvas is returned from +GPU Surface, returned by SkDocument::beginPage, returned by SkPictureRecorder::beginRecording, +or SkCanvas is the base of a utility class like SkDumpCanvas. + +Pixel values are converted only if Canvas Image Color Type and Image Alpha Type does not match dstInfo. +Only pixels within the rectangle that intersect Canvas pixels are copied. +dstPixels outside the rectangle intersection are unchanged. + +| source rectangle | value | +| --- | --- | +| left | srcX | +| top | srcY | +| width | dstInfo.width() | +| height | dstInfo.height() | + +| canvas pixel bounds | value | +| --- | --- | +| left | 0 | +| top | 0 | +| width | imageInfo.width() | +| height | imageInfo.height() | + +Does not copy, and returns false if: + + + + + + +
Source rectangle and canvas pixel bounds do not intersect.
Canvas pixels could not be converted to dstInfo Image Color Type or dstInfo Image Alpha Type.
Canvas pixels are not readable; for instance, Canvas is not raster, or is document-based.
dstRowBytes is too small to contain one row of pixels.
+ +### Parameters + + + + + + + +
dstInfo +Dimensions, Image Color Type, and Image Alpha Type of dstPixels.
dstPixels +Storage for pixels, of size dstInfo.height() times dstRowBytes.
dstRowBytes +Size of one destination row, dstInfo.width() times pixel size.
srcX +Offset into readable pixels in x.
srcY +Offset into readable pixels in y.
+ +### Return Value + +true if pixels were copied. + +### Example + +
Canvas returned by Raster Surface has premultiplied pixel values. +clear takes unpremultiplied input with Color Alpha equal 0x80 +and Color RGB equal 0x55, 0xAA, 0xFF. Color RGB is multipled by Color Alpha +to generate premultipled value 0x802B5580. readPixels converts pixel back +to unpremultipled value 0x8056A9FF, introducing error.
+ +#### Example Output + +~~~~ +pixel = 802b5580 +pixel = 8056a9ff +~~~~ + +
+ +--- + +
+bool readPixels(const SkPixmap& pixmap, int srcX, int srcY)
+
+ +Copies rectangle of pixels from Canvas into Pixmap, converting their Image Color Type and Image Alpha Type. +Pixels are readable when Device is raster. Pixels are not readable when SkCanvas is returned from +GPU Surface, returned by SkDocument::beginPage, returned by SkPictureRecorder::beginRecording, +or SkCanvas is the base of a utility class like SkDumpCanvas. + +Pixel values are converted only if Canvas Image Color Type and Image Alpha Type does not match bitmap Image Info. +Only Pixmap pixels within the rectangle that intersect Canvas pixels are copied. +Pixmap pixels outside the rectangle intersection are unchanged. + +| source rectangle | value | +| --- | --- | +| left | srcX | +| top | srcY | +| width | bitmap.width() | +| height | bitmap.height() | + +| canvas pixel bounds | value | +| --- | --- | +| left | 0 | +| top | 0 | +| width | imageInfo.width() | +| height | imageInfo.height() | + +Does not copy, and returns false if: + + + + + + + +
Source rectangle and canvas pixel bounds do not intersect.
Canvas pixels could not be converted to bitmap Image Color Type or bitmap Image Alpha Type.
Canvas pixels are not readable; for instance, Canvas is not raster, or is document-based.
bitmap pixels could not be allocated.
Bitmap Row Bytes is too small to contain one row of pixels.
+ +### Parameters + + + + + +
pixmap +Receives pixels copied from Canvas.
srcX +Offset into readable pixels in x.
srcY +Offset into readable pixels in y.
+ +### Return Value + +true if pixels were copied. + +### Example + +
+ +#### Example Output + +~~~~ +pixel = 802b5580 +~~~~ + +
+ +--- + +
+bool readPixels(const SkBitmap& bitmap, int srcX, int srcY)
+
+ +Copies pixels enclosed by bitmap offset to (x, y) from Canvas into bitmap, converting their Image Color Type and Image Alpha Type. +Pixels are readable when Device is raster. Pixels are not readable when SkCanvas is returned from +GPU Surface, returned by SkDocument::beginPage, returned by SkPictureRecorder::beginRecording, +or SkCanvas is the base of a utility class like SkDumpCanvas. +Allocates pixel storage in bitmap if needed. + +Pixel values are converted only if Canvas Image Color Type and Image Alpha Type does not match bitmap Image Info. +Only pixels within the rectangle that intersect Canvas pixels are copied. +Bitamp pixels outside the rectangle intersection are unchanged. + +| canvas pixel bounds | value | +| --- | --- | +| left | 0 | +| top | 0 | +| width | imageInfo.width() | +| height | imageInfo.height() | + +Does not copy, and returns false if: + + + + + + + +
Bounds formed by (x, y) and bitmap (width, height) and canvas pixel bounds do not intersect.
Canvas pixels could not be converted to bitmap Image Color Type or bitmap Image Alpha Type.
Canvas pixels are not readable; for instance, Canvas is not raster, or is document-based.
bitmap pixels could not be allocated.
Bitmap Row Bytes is too small to contain one row of pixels.
+ +### Parameters + + + + + +
bitmap +Receives pixels copied from Canvas.
srcX +Offset into readable pixels in x.
srcY +Offset into readable pixels in y.
+ +### Return Value + +true if pixels were copied. + +### Example + +
+ +#### Example Output + +~~~~ +pixel = 802b5580 +~~~~ + +
+ +--- + + +## writePixels + +
+bool writePixels(const SkImageInfo& info, const void* pixels, size_t rowBytes,
+                 int x, int y)
+
+ +Copies to Canvas pixels, ignoring the Matrix and Clip, converting to match +info Image Color Type and info Image Alpha Type. + +Pixel values are converted only if Canvas Image Color Type and Image Alpha Type does not match info. +Only pixels within the source rectangle that intersect Canvas pixel bounds are copied. +Canvas pixels outside the rectangle intersection are unchanged. + +| source rectangle | value | +| --- | --- | +| left | x | +| top | y | +| width | info.width() | +| height | info.height() | + +| canvas pixel bounds | value | +| --- | --- | +| left | 0 | +| top | 0 | +| width | imageInfo.width() | +| height | imageInfo.height() | + +Does not copy, and returns false if: + + + + + + +
Source rectangle and canvas pixel bounds do not intersect.
pixels could not be converted to Canvas Image Color Type or Canvas Image Alpha Type.
Canvas pixels are not writable; for instance, Canvas is document-based.
rowBytes is too small to contain one row of pixels.
+ +### Parameters + + + + + + + +
info +Dimensions, Image Color Type, and Image Alpha Type of pixels.
pixels +Pixels to copy, of size info.height() times rowBytes.
rowBytes +Offset from one row to the next, usually info.width() times pixel size.
x +Offset into Canvas writable pixels in x.
y +Offset into Canvas writable pixels in y.
+ +### Return Value + +true if pixels were written to Canvas. + +### Example + +
+ +--- + +
+bool writePixels(const SkBitmap& bitmap, int x, int y)
+
+ +Writes to Canvas pixels, ignoring the Matrix and Clip, converting to match +bitmap Image Color Type and bitmap Image Alpha Type. + +Pixel values are converted only if Canvas Image Color Type and Image Alpha Type does not match bitmap. +Only pixels within the source rectangle that intersect Canvas pixel bounds are copied. +Canvas pixels outside the rectangle intersection are unchanged. + +| source rectangle | value | +| --- | --- | +| left | x | +| top | y | +| width | bitmap.width() | +| height | bitmap.height() | + +| canvas pixel bounds | value | +| --- | --- | +| left | 0 | +| top | 0 | +| width | imageInfo.width() | +| height | imageInfo.height() | + +Does not copy, and returns false if: + + + + + + + +
Source rectangle and Canvas pixel bounds do not intersect.
bitmap does not have allocated pixels.
bitmap pixels could not be converted to Canvas Image Color Type or Canvas Image Alpha Type.
Canvas pixels are not writable; for instance, Canvas is document-based.
bitmap pixels are inaccessible; for instance, bitmap wraps a texture.
+ +### Parameters + + + + + +
bitmap +Provides pixels copied to Canvas.
x +Offset into Canvas writable pixels in x.
y +Offset into Canvas writable pixels in y.
+ +### Return Value + +true if pixels were written to Canvas. + +### Example + +
+ +--- + +# State Stack +Canvas maintains a stack of state that allows hierarchical drawing, commonly used +to implement windows and views. The initial state has an identity matrix and and an infinite clip. +Even with a wide-open clip, drawing is constrained by the bounds of the +Canvas Surface or Device. + +Canvas savable state consists of Clip, Matrix, and Draw Filter. +Clip describes the area that may be drawn to. +Matrix transforms the geometry. +Draw Filter (deprecated on most platforms) modifies the paint before drawing. + +save, saveLayer, saveLayerPreserveLCDTextRequests, and saveLayerAlpha +save state and return the depth of the stack. + +restore and restoreToCount revert state to its value when saved. + +Each state on the stack intersects Clip with the previous Clip, +and concatenates Matrix with the previous Matrix. +The intersected Clip makes the drawing area the same or smaller; +the concatenated Matrix may move the origin and potentially scale or rotate +the coordinate space. + +Canvas does not require balancing the state stack but it is a good idea +to do so. Calling save without restore will eventually cause Skia to fail; +mismatched save and restore create hard to find bugs. + +It is not possible to use state to draw outside of the clip defined by the +previous state. + +### Example + +
Draw to ever smaller clips; then restore drawing to full canvas. +Note that the second clipRect is not permitted to enlarge Clip.
+ +Each Clip uses the current Matrix for its coordinates. + +### Example + +
While clipRect is given the same rectangle twice, Matrix makes the second +clipRect draw at half the size of the first.
+ +### See Also + +save saveLayer saveLayerPreserveLCDTextRequests saveLayerAlpha restore restoreToCount + + +## save + +
+int save()
+
+ +Saves Matrix, Clip, and Draw Filter (Draw Filter deprecated on most platforms). +Calling restore discards changes to Matrix, Clip, and Draw Filter, +restoring the Matrix, Clip, and Draw Filter to their state when save was called. + +Matrix may be changed by translate, scale, rotate, skew, concat, setMatrix, and resetMatrix. +Clip may be changed by clipRect, clipRRect, clipPath, clipRegion. + +Saved Canvas state is put on a stack; multiple calls to save should be balance by an equal number of +calls to restore. + +Call restoreToCount with result to restore this and subsequent saves. + +### Return Value + +Depth of saved stack. + +### Example + +
The black square is translated 50 pixels down and to the right. +Restoring Canvas state removes translate from Canvas stack; +the red square is not translated, and is drawn at the origin.
+ +--- + +## Layer + +Layer allocates a temporary offscreen Bitmap to draw into. When the drawing is complete, +the Bitmap is drawn into the Canvas. + +Layer is saved in a stack along with other saved state. When state with a Layer +is restored, the offscreen Bitmap is drawn into the previous layer. + +Layer may be initialized with the contents of the previous layer. When Layer is +restored, its Bitmap can be modified by Paint passed to Layer to apply Color Alpha, +Color Filter, Image Filter, and Blend Mode. + + +## saveLayer + +
+int saveLayer(const SkRect* bounds, const SkPaint* paint)
+
+ +Saves Matrix, Clip, and Draw Filter (Draw Filter deprecated on most platforms), +and allocates an offscreen Bitmap for subsequent drawing. +Calling restore discards changes to Matrix, Clip, and Draw Filter, +and draws the offscreen bitmap. +The Matrix, Clip, and Draw Filter are restored to their state when save was called. + +Matrix may be changed by translate, scale, rotate, skew, concat, setMatrix, and resetMatrix. +Clip may be changed by clipRect, clipRRect, clipPath, clipRegion. + +Rect bounds suggests but does not define the offscreen size. To clip drawing to a specific rectangle, +use clipRect. + +Optional Paint paint applies Color Alpha, Color Filter, Image Filter, and Blend Mode when restore is called. + +Call restoreToCount with result to restore this and subsequent saves. + +### Parameters + + + + +
bounds +Used as a hint to limit the size of the offscreen; may be nullptr.
paint +Used when restore is called to draw the offscreen; may be nullptr.
+ +### Return Value + +Depth of saved stack. + +### Example + +
Rectangles are blurred by Image Filter when restore draws offscreen to main Canvas.
+ +--- + +
+int saveLayer(const SkRect& bounds, const SkPaint* paint)
+
+ +Saves Matrix, Clip, and Draw Filter (Draw Filter deprecated on most platforms), +and allocates an offscreen Bitmap for subsequent drawing. +Calling restore discards changes to Matrix, Clip, and Draw Filter, +and draws the offscreen Bitmap. +The Matrix, Clip, and Draw Filter are restored to their state when save was called. + +Matrix may be changed by translate, scale, rotate, skew, concat, setMatrix, and resetMatrix. +Clip may be changed by clipRect, clipRRect, clipPath, clipRegion. + +bounds suggests but does not define the offscreen size. To clip drawing to a specific rectangle, +use clipRect. + +Optional Paint paint applies Color Alpha, Color Filter, Image Filter, and Blend Mode when restore is called. + +Call restoreToCount with result to restore this and subsequent saves. + +### Parameters + + + + +
bounds +Used as a hint to limit the size of the offscreen; may be nullptr.
paint +Used when restore is called to draw the offscreen; may be nullptr.
+ +### Return Value + +Depth of saved stack. + +### Example + +
Rectangles are blurred by Image Filter when restore draws offscreen to main Canvas. +The red rectangle is clipped; it does not fully fit on the offscreen Canvas. +Image Filter blurs past edge of offscreen so red rectangle is blurred on all sides.
+ +--- + + +## saveLayerPreserveLCDTextRequests + +
+int saveLayerPreserveLCDTextRequests(const SkRect* bounds, const SkPaint* paint)
+
+ +Saves Matrix, Clip, and Draw Filter (Draw Filter deprecated on most platforms), +and allocates an offscreen bitmap for subsequent drawing. +LCD Text is preserved when the offscreen is drawn to the prior layer. + +Draw text on an opaque background so that LCD Text blends correctly with the prior layer. + +Calling restore discards changes to Matrix, Clip, and Draw Filter, +and draws the offscreen bitmap. +The Matrix, Clip, and Draw Filter are restored to their state when save was called. + +Matrix may be changed by translate, scale, rotate, skew, concat, setMatrix, and resetMatrix. +Clip may be changed by clipRect, clipRRect, clipPath, clipRegion. +Draw LCD Text on an opaque background to get good results. + +bounds suggests but does not define the offscreen size. To clip drawing to a specific rectangle, +use clipRect. + +paint modifies how the offscreen overlays the prior layer. Color Alpha, Blend Mode, +Color Filter, Draw Looper, Image Filter, and Mask Filter, affect the offscreen draw. + +Call restoreToCount with result to restore this and subsequent saves. + +### Parameters + + + + +
bounds +Used as a hint to limit the size of the offscreen; may be nullptr.
paint +Used when restore is called to draw the offscreen; may be nullptr.
+ +### Return Value + +Depth of saved stack. + +### Example + +
+ +--- + + +## saveLayerAlpha + +
+int saveLayerAlpha(const SkRect* bounds, U8CPU alpha)
+
+ +Saves Matrix, Clip, and Draw Filter (Draw Filter deprecated on most platforms), +and allocates an offscreen bitmap for subsequent drawing. + +Calling restore discards changes to Matrix, Clip, and Draw Filter, +and blends the offscreen bitmap with alpha opacity onto the prior layer. +The Matrix, Clip, and Draw Filter are restored to their state when save was called. + +Matrix may be changed by translate, scale, rotate, skew, concat, setMatrix, and resetMatrix. +Clip may be changed by clipRect, clipRRect, clipPath, clipRegion. + +bounds suggests but does not define the offscreen size. To clip drawing to a specific rectangle, +use clipRect. + +Call restoreToCount with result to restore this and subsequent saves. + +### Parameters + + + + +
bounds +Used as a hint to limit the size of the offscreen; may be nullptr.
alpha +The opacity of the offscreen; zero is fully transparent, 255 is fully opaque.
+ +### Return Value + +Depth of saved stack. + +### Example + +
+ +--- + +## Enum SkCanvas::SaveLayerFlags + +
+enum {
+kIsOpaque SaveLayerFlag = 1 << 0,
+kPreserveLCDText SaveLayerFlag = 1 << 1,
+kInitWithPrevious SaveLayerFlag = 1 << 2,
+};
+
+typedef uint32_t SaveLayerFlags;
+ +SaveLayerFlags provides options that may be used in any combination in SaveLayerRec, +defining how the offscreen allocated by saveLayer operates. + +### Constants + + + + + + + + + + + +
SkCanvas::kIsOpaque_SaveLayerFlag 1Creates offscreen without transparency. Flag is ignored if layer Paint contains +Image Filter or Color Filter.
SkCanvas::kPreserveLCDText_SaveLayerFlag 2Creates offscreen for LCD text. Flag is ignored if layer Paint contains +Image Filter or Color Filter.
SkCanvas::kInitWithPrevious_SaveLayerFlag 4Initializes offscreen with the contents of the previous layer.
+ +### Example + +
Canvas layer captures red and blue circles scaled up by four. +scalePaint blends offscreen back with transparency.
+ + + +# Struct SkCanvas::SaveLayerRec + +
+struct SaveLayerRec {
+SaveLayerRec*(...
+
+const SkRect*           fBounds;
+const SkPaint*          fPaint;
+const SkImageFilter*    fBackdrop;
+SaveLayerFlags          fSaveLayerFlags;
+};
+ +SaveLayerRec contains the state used to create the layer offscreen. + +const SkRect* fBounds + +fBounds is used as a hint to limit the size of the offscreen; may be nullptr. +fBounds suggests but does not define the offscreen size. To clip drawing to a specific rectangle, +use clipRect. + +const SkPaint* fPaint + +fPaint modifies how the offscreen overlays the prior layer; may be nullptr. Color Alpha, Blend Mode, +Color Filter, Draw Looper, Image Filter, and Mask Filter affect the offscreen draw. + +const SkImageFilter* fBackdrop + +fBackdrop applies Image Filter to the prior layer when copying to the layer offscreen; may be nullptr. +Use kInitWithPrevious SaveLayerFlag to copy the prior layer without a Image Filter. + +const SkImage* fClipMask + +may be nullptr. + +const SkMatrix* fClipMatrix + +may be nullptr. + +SaveLayerFlags fSaveLayerFlags + +fSaveLayerFlags are used to create layer offscreen without transparency, create layer offscreen for +LCD text, and to create layer offscreen with the contents of the previous layer. + +### Example + +
Canvas layer captures a red anti-aliased circle and a blue aliased circle scaled up by four. +After drawing another unscaled red circle on top, the offscreen is transferred to the main canvas.
+ + +## SaveLayerRec + +
+SaveLayerRec()
+
+ +Sets fBounds, fPaint, and fBackdrop to nullptr. Clears fSaveLayerFlags. + +### Return Value + +empty SaveLayerRec. + +### Example + +
+ +#### Example Output + +~~~~ +rec1 == rec2 +~~~~ + +
+ +--- + +
+SaveLayerRec(const SkRect* bounds, const SkPaint* paint,
+             SaveLayerFlags saveLayerFlags = 0)
+
+ +Sets fBounds, fPaint, and fSaveLayerFlags; sets fBackdrop to nullptr. + +### Parameters + + + + + +
bounds +Offscreen dimensions; may be nullptr.
paint +Applied to offscreen when overlaying prior layer; may be nullptr.
saveLayerFlags +SaveLayerRec options to modify offscreen.
+ +### Return Value + +SaveLayerRec with empty backdrop. + +### Example + +
+ +#### Example Output + +~~~~ +rec1 == rec2 +~~~~ + +
+ +--- + +
+SaveLayerRec(const SkRect* bounds, const SkPaint* paint,
+             const SkImageFilter* backdrop, SaveLayerFlags saveLayerFlags)
+
+ +Sets fBounds, fPaint, fBackdrop, and fSaveLayerFlags. + +### Parameters + + + + + + +
bounds +Offscreen dimensions; may be nullptr.
paint +Applied to offscreen when overlaying prior layer; may be nullptr.
backdrop +Copies prior layer to offscreen with Image Filter; may be nullptr.
saveLayerFlags +SaveLayerRec options to modify offscreen.
+ +### Return Value + +SaveLayerRec fully specified. + +### Example + +
+ +#### Example Output + +~~~~ +rec1 == rec2 +~~~~ + +
+ +--- + +
+SaveLayerRec(const SkRect* bounds, const SkPaint* paint,
+             const SkImageFilter* backdrop, const SkImage* clipMask,
+             const SkMatrix* clipMatrix, SaveLayerFlags saveLayerFlags)
+
+ +Not ready for general use. + +### Parameters + + + + + + + + +
bounds +Offscreen dimensions; may be nullptr.
paint +Applied to offscreen when overlaying prior layer; may be nullptr.
backdrop +Copies prior layer to offscreen with Image Filter; may be nullptr.
clipMask +May be nullptr.
clipMatrix +May be nullptr.
saveLayerFlags +SaveLayerRec options to modify offscreen.
+ +### Return Value + +SaveLayerRec fully specified. + +--- + +
+int saveLayer(const SaveLayerRec& layerRec)
+
+ +Saves Matrix, Clip, and Draw Filter (Draw Filter deprecated on most platforms), +and allocates an offscreen bitmap for subsequent drawing. + +Calling restore discards changes to Matrix, Clip, and Draw Filter, +and blends the offscreen bitmap with alpha opacity onto the prior layer. +The Matrix, Clip, and Draw Filter are restored to their state when save was called. + +Matrix may be changed by translate, scale, rotate, skew, concat, setMatrix, and resetMatrix. +Clip may be changed by clipRect, clipRRect, clipPath, clipRegion. + +SaveLayerRec contains the state used to create the layer offscreen. + +Call restoreToCount with result to restore this and subsequent saves. + +### Parameters + + + +
layerRec +offscreen state.
+ +### Return Value + +depth of save state stack. + +### Example + +
The example draws an image, and saves it into a layer with kInitWithPrevious SaveLayerFlag. +Next it punches a hole in the layer and restore with SkBlendMode::kPlus. +Where the layer was cleared, the original image will draw unchanged. +Outside of the circle the mandrill is brightened.
+ +--- + + +## restore + +
+void restore()
+
+ +Removes changes to Matrix, Clip, and Draw Filter since Canvas state was +last saved. The state is removed from the stack. + +Does nothing if the stack is empty. + +### Example + +
+ +--- + + +## getSaveCount + +
+int getSaveCount() const
+
+ +Returns the number of saved states, each containing: Matrix, Clip, and Draw Filter. +Equals the number of save calls less the number of restore calls plus one. +The save count of a new canvas is one. + +### Return Value + +depth of save state stack. + +### Example + +
+ +#### Example Output + +~~~~ +depth = 1 +depth = 2 +depth = 1 +~~~~ + +
+ +--- + + +## restoreToCount + +
+void restoreToCount(int saveCount)
+
+ +Restores state to Matrix, Clip, and Draw Filter +values when save, saveLayer, saveLayerPreserveLCDTextRequests, or saveLayerAlpha +returned saveCount. + +Does nothing if saveCount is greater than state stack count. +Restores state to initial values if saveCount is less than or equal to one. + +### Parameters + + + +
saveCount +The depth of state stack to restore.
+ +### Example + +
+ +#### Example Output + +~~~~ +depth = 1 +depth = 3 +depth = 1 +~~~~ + +
+ +--- + +# Matrix + + +## translate + +
+void translate(SkScalar dx, SkScalar dy)
+
+ +Translate Matrix by dx along the x-axis and dy along the y-axis. + +Mathematically, replace Matrix with a translation matrix +pre-multiplied with Matrix. + +This has the effect of moving the drawing by (dx, dy) before transforming +the result with Matrix. + +### Parameters + + + + +
dx +The distance to translate in x.
dy +The distance to translate in y.
+ +### Example + +
scale followed by translate produces different results from translate followed +by scale. + +The blue stroke follows translate of (50, 50); a black +fill follows scale of (2, 1/2.f). After restoring the clip, which resets +Matrix, a red frame follows the same scale of (2, 1/2.f); a gray fill +follows translate of (50, 50).
+ +--- + + +## scale + +
+void scale(SkScalar sx, SkScalar sy)
+
+ +Scale Matrix by sx on the x-axis and sy on the y-axis. + +Mathematically, replace Matrix with a scale matrix +pre-multiplied with Matrix. + +This has the effect of scaling the drawing by (sx, sy) before transforming +the result with Matrix. + +### Parameters + + + + +
sx +The amount to scale in x.
sy +The amount to scale in y.
+ +### Example + +
+ +--- + + +## rotate + +
+void rotate(SkScalar degrees)
+
+ +Rotate Matrix by degrees. Positive degrees rotates clockwise. + +Mathematically, replace Matrix with a rotation matrix +pre-multiplied with Matrix. + +This has the effect of rotating the drawing by degrees before transforming +the result with Matrix. + +### Parameters + + + +
degrees +The amount to rotate, in degrees.
+ +### Example + +
Draw clock hands at time 5:10. The hour hand and minute hand point up and +are rotated clockwise.
+ +--- + +
+void rotate(SkScalar degrees, SkScalar px, SkScalar py)
+
+ +Rotate Matrix by degrees about a point at (px, py). Positive degrees rotates clockwise. + +Mathematically, construct a rotation matrix. Pre-multiply the rotation matrix by +a translation matrix, then replace Matrix with the resulting matrix +pre-multiplied with Matrix. + +This has the effect of rotating the drawing about a given point before transforming +the result with Matrix. + +### Parameters + + + + + +
degrees +The amount to rotate, in degrees.
px +The x coordinate of the point to rotate about.
py +The y coordinate of the point to rotate about.
+ +### Example + +
+ +--- + + +## skew + +
+void skew(SkScalar sx, SkScalar sy)
+
+ +Skew Matrix by sx on the x-axis and sy on the y-axis. A positive value of sx skews the +drawing right as y increases; a positive value of sy skews the drawing down as x increases. + +Mathematically, replace Matrix with a skew matrix +pre-multiplied with Matrix. + +Preconcat the current matrix with the specified skew. + +### Parameters + + + + +This has the effect of scaling the drawing by (sx, sy) before transforming +the result with Matrix. + +
sx +The amount to skew in x.
sy +The amount to skew in y.
+ +### Example + +
Black text mimics an oblique text style by using a negative skew in x that +shifts the geometry to the right as the y values decrease. +Red text uses a positive skew in y to shift the geometry down as the x values +increase. +Blue text combines x and y skew to rotate and scale.
+ +--- + + +## concat + +
+void concat(const SkMatrix& matrix)
+
+ +Replace Matrix with matrix pre-multiplied with Matrix. + +This has the effect of transforming the drawn geometry by matrix, before transforming +the result with Matrix. + +### Parameters + + + +
matrix +Pre-multiply with Matrix.
+ +### Example + +
+ +--- + + +## setMatrix + +
+void setMatrix(const SkMatrix& matrix)
+
+ +Replace Matrix with matrix. +Unlike concat, any prior matrix state is overwritten. + +### Parameters + + + +
matrix +Copied into Matrix.
+ +### Example + +
+ +--- + + +## resetMatrix + +
+void resetMatrix()
+
+ +Sets Matrix to the identity matrix. +Any prior matrix state is overwritten. + +### Example + +
+ +--- + + +## getTotalMatrix + +
+const SkMatrix& getTotalMatrix() const
+
+ +Returns Matrix. +This does not account for translation by Device or Surface. + +### Return Value + +Matrix on Canvas. + +### Example + +
+ +#### Example Output + +~~~~ +isIdentity true +~~~~ + +
+ +--- + +# Clip +Clip is built from a stack of clipping paths. Each Path in the +stack can be constructed from one or more Path Contour elements. The +Path Contour may be composed of any number of Path Verb segments. Each +Path Contour forms a closed area; Path Fill Type defines the area enclosed +by Path Contour. + +Clip stack of Path elements successfully restrict the Path area. Each +Path is transformed by Matrix, then intersected with or subtracted from the +prior Clip to form the replacement Clip. Use SkClipOp::kDifference +to subtract Path from Clip; use SkClipOp::kIntersect to intersect Path +with Clip. + +A clipping Path may be anti-aliased; if Path, after transformation, is +composed of horizontal and vertical lines, clearing Anti-alias allows whole pixels +to either be inside or outside the clip. The fastest drawing has a aliased, +rectanglar clip. + +If clipping Path has Anti-alias set, clip may partially clip a pixel, requiring +that drawing blend partially with the destination along the edge. A rotated +rectangular anti-aliased clip looks smoother but draws slower. + +Clip can combine with Rect and Round Rect primitives; like +Path, these are transformed by Matrix before they are combined with Clip. + +Clip can combine with Region. Region is assumed to be in Device coordinates +and is unaffected by Matrix. + +### Example + +
Draw a red circle with an aliased clip and an anti-aliased clip. +Use an image filter to zoom into the pixels drawn. +The edge of the aliased clip fully draws pixels in the red circle. +The edge of the anti-aliased clip partially draws pixels in the red circle.
+ + +## clipRect + +
+void clipRect(const SkRect& rect, SkClipOp op, bool doAntiAlias)
+
+ +Replace Clip with the intersection or difference of Clip and rect, +with an aliased or anti-aliased clip edge. rect is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + + +
rect +Rectangle to combine with Clip.
op +Clip Op to apply to Clip.
doAntiAlias +true if Clip is to be anti-aliased.
+ +### Example + +
+ +--- + +
+void clipRect(const SkRect& rect, SkClipOp op)
+
+ +Replace Clip with the intersection or difference of Clip and rect. +Resulting Clip is aliased; pixels are fully contained by the clip. +rect is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + +
rect +Rectangle to combine with Clip.
op +Clip Op to apply to Clip.
+ +### Example + +
+ +--- + +
+void clipRect(const SkRect& rect, bool doAntiAlias = false)
+
+ +Replace Clip with the intersection of Clip and rect. +Resulting Clip is aliased; pixels are fully contained by the clip. +rect is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + +
rect +Rectangle to combine with Clip.
doAntiAlias +true if Clip is to be anti-aliased.
+ +### Example + +
A circle drawn in pieces looks uniform when drawn aliased. +The same circle pieces blend with pixels more than once when anti-aliased, +visible as a thin pair of lines through the right circle.
+ +--- + + +## androidFramework_setDeviceClipRestriction + +
+void androidFramework_setDeviceClipRestriction(const SkIRect& rect)
+
+ +Sets the max clip rectangle, which can be set by clipRect, clipRRect and +clipPath and intersect the current clip with the specified rect. +The max clip affects only future ops (it is not retroactive). +The clip restriction is not recorded in pictures. + +### Parameters + + + + +--- + +
rect +The maximum allowed clip in device coordinates.
+ + +## clipRRect + +
+void clipRRect(const SkRRect& rrect, SkClipOp op, bool doAntiAlias)
+
+ +Replace Clip with the intersection or difference of Clip and rrect, +with an aliased or anti-aliased clip edge. +rrect is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + + +
rrect +Round Rect to combine with Clip.
op +Clip Op to apply to Clip.
doAntiAlias +true if Clip is to be antialiased.
+ +### Example + +
+ +--- + +
+void clipRRect(const SkRRect& rrect, SkClipOp op)
+
+ +Replace Clip with the intersection or difference of Clip and rrect. +Resulting Clip is aliased; pixels are fully contained by the clip. +rrect is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + +
rrect +Round Rect to combine with Clip.
op +Clip Op to apply to Clip.
+ +### Example + +
+ +--- + +
+void clipRRect(const SkRRect& rrect, bool doAntiAlias = false)
+
+ +Replace Clip with the intersection of Clip and rrect, +with an aliased or anti-aliased clip edge. +rrect is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + +
rrect +Round Rect to combine with Clip.
doAntiAlias +true if Clip is to be antialiased.
+ +### Example + +
+ +--- + + +## clipPath + +
+void clipPath(const SkPath& path, SkClipOp op, bool doAntiAlias)
+
+ +Replace Clip with the intersection or difference of Clip and path, +with an aliased or anti-aliased clip edge. Path Fill Type determines if path +describes the area inside or outside its contours; and if Path Contour overlaps +itself or another Path Contour, whether the overlaps form part of the area. +path is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + + +
path +Path to combine with Clip.
op +Clip Op to apply to Clip.
doAntiAlias +true if Clip is to be antialiased.
+ +### Example + +
Top figure uses SkPath::kInverseWinding FillType and SkClipOp::kDifference; +area outside clip is subtracted from circle. + +Bottom figure uses SkPath::kWinding FillType and SkClipOp::kIntersect; +area inside clip is intersected with circle.
+ +--- + +
+void clipPath(const SkPath& path, SkClipOp op)
+
+ +Replace Clip with the intersection or difference of Clip and path. +Resulting Clip is aliased; pixels are fully contained by the clip. +Path Fill Type determines if path +describes the area inside or outside its contours; and if Path Contour overlaps +itself or another Path Contour, whether the overlaps form part of the area. +path is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + +
path +Path to combine with Clip.
op +Clip Op to apply to Clip.
+ +### Example + +
Overlapping Rects form a clip. When clip's Path Fill Type is set to +SkPath::kWinding FillType, the overlap is included. Set to +SkPath::kEvenOdd FillType, the overlap is excluded and forms a hole.
+ +--- + +
+void clipPath(const SkPath& path, bool doAntiAlias = false)
+
+ +Replace Clip with the intersection of Clip and path. +Resulting Clip is aliased; pixels are fully contained by the clip. +Path Fill Type determines if path +describes the area inside or outside its contours; and if Path Contour overlaps +itself or another Path Contour, whether the overlaps form part of the area. +path is transformed by Matrix +before it is combined with Clip. + +### Parameters + + + + +
path +Path to combine with Clip.
doAntiAlias +true if Clip is to be antialiased.
+ +### Example + +
Clip loops over itself covering its center twice. When clip's Path Fill Type +is set to SkPath::kWinding FillType, the overlap is included. Set to +SkPath::kEvenOdd FillType, the overlap is excluded and forms a hole.
+ +--- + + +## setAllowSimplifyClip + +
+void setAllowSimplifyClip(bool allow)
+
+ +Only used for testing.Set to simplify clip stack using path ops. + +--- + + +## clipRegion + +
+void clipRegion(const SkRegion& deviceRgn, SkClipOp op = SkClipOp::kIntersect)
+
+ +Replace Clip with the intersection or difference of Clip and Region deviceRgn. +Resulting Clip is aliased; pixels are fully contained by the clip. +deviceRgn is unaffected by Matrix. + +### Parameters + + + + +
deviceRgn +Region to combine with Clip.
op +Clip Op to apply to Clip.
+ +### Example + +
region is unaffected by canvas rotation; rect is affected by canvas rotation. +Both clips are aliased; this is unnoticable on Region clip because it +aligns to pixel boundaries.
+ +--- + + +## quickReject + +
+bool quickReject(const SkRect& rect) const
+
+ +Return true if Rect rect, transformed by Matrix, can be quickly determined to be +outside of Clip. May return false even though rect is outside of Clip. + +Use to check if an area to be drawn is clipped out, to skip subsequent draw calls. + +### Parameters + + + +
rect +Rect to compare with Clip.
+ +### Return Value + +true if rect, transformed by Matrix, does not intersect Clip. + +### Example + +
+ +#### Example Output + +~~~~ +quickReject true +quickReject false +~~~~ + +
+ +--- + +
+bool quickReject(const SkPath& path) const
+
+ +Return true if path, transformed by Matrix, can be quickly determined to be +outside of Clip. May return false even though path is outside of Clip. + +Use to check if an area to be drawn is clipped out, to skip subsequent draw calls. + +### Parameters + + + +
path +Path to compare with Clip.
+ +### Return Value + +true if path, transformed by Matrix, does not intersect Clip. + +### Example + +
+ +#### Example Output + +~~~~ +quickReject true +quickReject false +~~~~ + +
+ +--- + + +## getLocalClipBounds + +
+SkRect getLocalClipBounds() const
+
+ +Return bounds of Clip, transformed by inverse of Matrix. If Clip is empty, +return SkRect::MakeEmpty, where all Rect sides equal zero. + +Rect returned is outset by one to account for partial pixel coverage if Clip +is anti-aliased. + +### Return Value + +bounds of Clip in local coordinates. + +### Example + +
Initial bounds is device bounds outset by 1 on all sides. +Clipped bounds is clipPath bounds outset by 1 on all sides. +Scaling the canvas by two in x and y scales the local bounds by 1/2 in x and y.
+ +#### Example Output + +~~~~ +left:-1 top:-1 right:257 bottom:257 +left:29 top:129 right:121 bottom:231 +left:14.5 top:64.5 right:60.5 bottom:115.5 +~~~~ + +
+ +--- + +
+bool getLocalClipBounds(SkRect* bounds) const
+
+ +Return bounds of Clip, transformed by inverse of Matrix. If Clip is empty, +return false, and set bounds to SkRect::MakeEmpty, where all Rect sides equal zero. + +bounds is outset by one to account for partial pixel coverage if Clip +is anti-aliased. + +### Parameters + + + +
bounds +Rect of Clip in local coordinates.
+ +### Return Value + +true if Clip bounds is not empty. + +### Example + +
+ +#### Example Output + +~~~~ +local bounds empty = false +local bounds empty = true +~~~~ + +
+ +--- + + +## getDeviceClipBounds + +
+SkIRect getDeviceClipBounds() const
+
+ +Return IRect bounds of Clip, unaffected by Matrix. If Clip is empty, +return SkRect::MakeEmpty, where all Rect sides equal zero. + +Unlike getLocalClipBounds, returned IRect is not outset. + +### Return Value + +bounds of Clip in Device coordinates. + +### Example + +
Initial bounds is device bounds, not outset. +Clipped bounds is clipPath bounds, not outset. +Scaling the canvas by 1/2 in x and y scales the device bounds by 1/2 in x and y.
+ +#### Example Output + +~~~~ +left:0 top:0 right:256 bottom:256 +left:30 top:130 right:120 bottom:230 +left:15 top:65 right:60 bottom:115 +~~~~ + +
+ +--- + +
+bool getDeviceClipBounds(SkIRect* bounds) const
+
+ +Return IRect bounds of Clip, unaffected by Matrix. If Clip is empty, +return false, and set bounds to SkRect::MakeEmpty, where all Rect sides equal zero. + +Unlike getLocalClipBounds, bounds is not outset. + +### Parameters + + + +
bounds +Rect of Clip in device coordinates.
+ +### Return Value + +true if Clip bounds is not empty. + +### Example + +
+ +#### Example Output + +~~~~ +device bounds empty = false +device bounds empty = true +~~~~ + +
+ +--- + + +## drawColor + +
+void drawColor(SkColor color, SkBlendMode mode = SkBlendMode::kSrcOver)
+
+ +Fill Clip with Color color. +mode determines how Color ARGB is combined with destination. + +### Parameters + + + + +
color +Unpremultiplied Color ARGB.
mode +SkBlendMode used to combine source color and destination.
+ +### Example + +
+ +--- + + +## clear + +
+void clear(SkColor color)
+
+ +Fill Clip with Color color using SkBlendMode::kSrc. +This has the effect of replacing all pixels contained by Clip with color. + +### Parameters + + + +
color +Unpremultiplied Color ARGB.
+ +### Example + +
+ +--- + + +## discard + +
+void discard()
+
+ +Make Canvas contents undefined. Subsequent calls that read Canvas pixels, +such as drawing with SkBlendMode, return undefined results. discard does +not change Clip or Matrix. + +discard may do nothing, depending on the implementation of Surface or Device +that created Canvas. + +discard allows optimized performance on subsequent draws by removing +cached data associated with Surface or Device. +It is not necessary to call discard once done with Canvas; +any cached data is deleted when owning Surface or Device is deleted. + +--- + + +## drawPaint + +
+void drawPaint(const SkPaint& paint)
+
+ +Fill Clip with Paint paint. drawPaint is affected by Paint components +Rasterizer, Mask Filter, Shader, Color Filter, Image Filter, and Blend Mode; but not by +Path Effect. + +### Parameters + + + +
paint +Used to fill the canvas.
+ +### Example + +
+ +--- + +## Enum SkCanvas::PointMode + +
+enum PointMode {
+kPoints PointMode,
+kLines PointMode,
+kPolygon PointMode 
+};
+ +Selects if an array of points are drawn as discrete points, as lines, or as +an open polygon. + +### Constants + + + + + + + + + + + +
SkCanvas::kPoints_PointMode 0Draw each point separately.
SkCanvas::kLines_PointMode 1Draw each pair of points as a line segment.
SkCanvas::kPolygon_PointMode 2Draw the array of points as a open polygon.
+ +### Example + +
The upper left corner shows three squares when drawn as points. +The upper right corner shows one line; when drawn as lines, two points are required per line. +The lower right corner shows two lines; when draw as polygon, no miter is drawn at the corner. +The lower left corner shows two lines with a miter when path contains polygon.
+ + + + +## drawPoints + +
+void drawPoints(PointMode mode, size_t count, const SkPoint pts[],
+                const SkPaint& paint)
+
+ +Draw pts using Clip, Matrix and Paint paint. +count is the number of points; if count is less than one, drawPoints has no effect. +mode may be one of: kPoints PointMode, kLines PointMode, or kPolygon PointMode. + +If mode is kPoints PointMode, the shape of point drawn depends on paint Paint Stroke Cap. +If paint is set to SkPaint::kRound Cap, each point draws a circle of diameter Paint Stroke Width. +If paint is set to SkPaint::kSquare Cap or SkPaint::kButt Cap, +each point draws a square of width and height Paint Stroke Width. + +If mode is kLines PointMode, each pair of points draws a line segment. +One line is drawn for every two points; each point is used once. If count is odd, +the final point is ignored. + +If mode is kPolygon PointMode, each adjacent pair of points draws a line segment. +count minus one lines are drawn; the first and last point are used once. + +Each line segment respects paint Paint Stroke Cap and Paint Stroke Width. +Paint Style is ignored, as if were set to SkPaint::kStroke Style. + +drawPoints always draws each element one at a time; drawPoints is not affected by +Paint Stroke Join, and unlike drawPath, does not create a mask from all points and lines +before drawing. + +### Parameters + + + + + + +
mode +Whether pts draws points or lines.
count +The number of points in the array.
pts +Array of points to draw.
paint +Stroke, blend, color, and so on, used to draw.
+ +### Example + +
+ + + + + + + + + +
The first column draws points.
The second column draws points as lines.
The third column draws points as a polygon.
The fourth column draws points as a polygonal path.
The first row uses a round cap and round join.
The second row uses a square cap and a miter join.
The third row uses a butt cap and a bevel join.
+ +The transparent color makes multiple line draws visible; +the path is drawn all at once.
+ +--- + + +## drawPoint + +
+void drawPoint(SkScalar x, SkScalar y, const SkPaint& paint)
+
+ +Draw point at (x, y) using Clip, Matrix and Paint paint. + +The shape of point drawn depends on paint Paint Stroke Cap. +If paint is set to SkPaint::kRound Cap, draw a circle of diameter Paint Stroke Width. +If paint is set to SkPaint::kSquare Cap or SkPaint::kButt Cap, +draw a square of width and height Paint Stroke Width. +Paint Style is ignored, as if were set to SkPaint::kStroke Style. + +### Parameters + + + + + +
x +Left edge of circle or square.
y +Top edge of circle or square.
paint +Stroke, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawLine + +
+void drawLine(SkScalar x0, SkScalar y0, SkScalar x1, SkScalar y1,
+              const SkPaint& paint)
+
+ +Draw line segment from (x0, y0) to (x1, y1) using Clip, Matrix, and Paint paint. +In paint: Paint Stroke Width describes the line thickness; Paint Stroke Cap draws the end rounded or square; +Paint Style is ignored, as if were set to SkPaint::kStroke Style. + +### Parameters + + + + + + + +
x0 +Start of line segment on x-axis.
y0 +Start of line segment on y-axis.
x1 +End of line segment on x-axis.
y1 +End of line segment on y-axis.
paint +Stroke, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawRect + +
+void drawRect(const SkRect& rect, const SkPaint& paint)
+
+ +Draw Rect rect using Clip, Matrix, and Paint paint. +In paint: Paint Style determines if rectangle is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness, and +Paint Stroke Join draws the corners rounded or square. + +### Parameters + + + + +
rect +The rectangle to be drawn.
paint +Stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawIRect + +
+void drawIRect(const SkIRect& rect, const SkPaint& paint)
+
+ +Draw IRect rect using Clip, Matrix, and Paint paint. +In paint: Paint Style determines if rectangle is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness, and +Paint Stroke Join draws the corners rounded or square. + +### Parameters + + + + +
rect +The rectangle to be drawn.
paint +Stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawRegion + +
+void drawRegion(const SkRegion& region, const SkPaint& paint)
+
+ +Draw Region region using Clip, Matrix, and Paint paint. +In paint: Paint Style determines if rectangle is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness, and +Paint Stroke Join draws the corners rounded or square. + +### Parameters + + + + +
region +The region to be drawn.
paint +Paint stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawOval + +
+void drawOval(const SkRect& oval, const SkPaint& paint)
+
+ +Draw Oval oval using Clip, Matrix, and Paint. +In paint: Paint Style determines if Oval is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness. + +### Parameters + + + + +
oval +Rect bounds of Oval.
paint +Paint stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawRRect + +
+void drawRRect(const SkRRect& rrect, const SkPaint& paint)
+
+ +Draw Round Rect rrect using Clip, Matrix, and Paint paint. +In paint: Paint Style determines if rrect is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness. + +rrect may represent a rectangle, circle, oval, uniformly rounded rectangle, or may have +any combination of positive non-square radii for the four corners. + +### Parameters + + + + +
rrect +Round Rect with up to eight corner radii to draw.
paint +Paint stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawDRRect + +
+void drawDRRect(const SkRRect& outer, const SkRRect& inner, const SkPaint& paint)
+
+ +Draw Round Rect outer and inner +using Clip, Matrix, and Paint paint. +outer must contain inner or the drawing is undefined. +In paint: Paint Style determines if rrect is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness. +If stroked and Round Rect corner has zero length radii, Paint Stroke Join can draw +corners rounded or square. + +GPU-backed platforms take advantage of drawDRRect since both outer and inner are +concave and outer contains inner. These platforms may not be able to draw +Path built with identical data as fast. + +### Parameters + + + + + +
outer +Round Rect outer bounds to draw.
inner +Round Rect inner bounds to draw.
paint +Paint stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +### Example + +
Outer Rect has no corner radii, but stroke join is rounded. +Inner Round Rect has corner radii; outset stroke increases radii of corners. +Stroke join does not affect inner Round Rect since it has no sharp corners.
+ +--- + + +## drawCircle + +
+void drawCircle(SkScalar cx, SkScalar cy, SkScalar radius, const SkPaint& paint)
+
+ +Draw Circle at (cx, cy) with radius using Clip, Matrix, and Paint paint. +If radius is zero or less, nothing is drawn. +In paint: Paint Style determines if Circle is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness. + +### Parameters + + + + + + +
cx +Circle center on the x-axis.
cy +Circle center on the y-axis.
radius +Half the diameter of Circle.
paint +Paint stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawArc + +
+void drawArc(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle,
+             bool useCenter, const SkPaint& paint)
+
+ +Draw Arc using Clip, Matrix, and Paint paint. +Arc is part of Oval bounded by oval, sweeping from startAngle to startAngle plus +sweepAngle. startAngle and sweepAngle are in degrees. +startAngle of zero places start point at the right middle edge of oval. +A positive sweepAngle places Arc end point clockwise from start point; +a negative sweepAngle places Arc end point counterclockwise from start point. +sweepAngle may exceed 360 degrees, a full circle. +If useCenter is true, draw a wedge that includes lines from oval +center to Arc end points. If useCenter is false, draw Arc between end points. + +If Rect oval is empty or sweepAngle is zero, nothing is drawn. + +### Parameters + + + + + + + +
oval +Rect bounds of Oval containing Arc to draw.
startAngle +Angle in degrees where Arc begins.
sweepAngle +Sweep angle in degrees; positive is clockwise.
useCenter +If true include the center of the oval.
paint +Paint stroke or fill, blend, color, and so on, used to draw.
+ +### Example + +
+ +### Example + +
+ +--- + + +## drawRoundRect + +
+void drawRoundRect(const SkRect& rect, SkScalar rx, SkScalar ry,
+                   const SkPaint& paint)
+
+ +Draw Round Rect bounded by Rect rect, with corner radii (rx, ry) using Clip, Matrix, +and Paint paint. +In paint: Paint Style determines if Round Rect is stroked or filled; +if stroked, Paint Stroke Width describes the line thickness. +If rx or ry are less than zero, they are treated as if they are zero. +If rx plus ry exceeds rect width or rect height, radii are scaled down to fit. +If rx and ry are zero, Round Rect is drawn as Rect and if stroked is affected by Paint Stroke Join. + +### Parameters + + + + + + +
rect +Rect bounds of Round Rect to draw.
rx +Semiaxis length in x of oval describing rounded corners.
ry +Semiaxis length in y of oval describing rounded corners.
paint +Stroke, blend, color, and so on, used to draw.
+ +### Example + +
Top row has a zero radius a generates a rectangle. +Second row radii sum to less than sides. +Third row radii sum equals sides. +Fourth row radii sum exceeds sides; radii are scaled to fit.
+ +--- + + +## drawPath + +
+void drawPath(const SkPath& path, const SkPaint& paint)
+
+ +Draw Path path using Clip, Matrix, and Paint paint. +Path contains an array of Path Contour, each of which may be open or closed. + +In paint: Paint Style determines if Round Rect is stroked or filled: +if filled, Path Fill Type determines whether Path Contour describes inside or outside of fill; +if stroked, Paint Stroke Width describes the line thickness, Paint Stroke Cap describes line ends, +and Paint Stroke Join describes how corners are drawn. + +### Parameters + + + + +
path +Path to draw.
paint +Stroke, blend, color, and so on, used to draw.
+ +### Example + +
Top rows draw stroked path with combinations of joins and caps. The open contour +is affected by caps; the closed contour is affected by joins. +Bottom row draws fill the same for open and closed contour. +First bottom column shows winding fills overlap. +Second bottom column shows even odd fills exclude overlap. +Third bottom column shows inverse winding fills area outside both contours.
+ +--- + +# Draw Image +drawImage, drawImageRect, and drawImageNine can be called with a bare pointer or a smart pointer as a convenience. +The pairs of calls are otherwise identical. + + +## drawImage + +
+void drawImage(const SkImage* image, SkScalar left, SkScalar top,
+               const SkPaint* paint = NULL)
+
+ +Draw Image image, with its top-left corner at (left, top), +using Clip, Matrix, and optional Paint paint. + +If paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
image +Uncompressed rectangular map of pixels.
left +Left side of image.
top +Top side of image.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
+ +--- + +
+void drawImage(const sk_sp& image, SkScalar left, SkScalar top,
+               const SkPaint* paint = NULL)
+
+ +Draw Image image, with its top-left corner at (left, top), +using Clip, Matrix, and optional Paint paint. + +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
image +Uncompressed rectangular map of pixels.
left +Left side of image.
top +Top side of image.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
+ +--- + +## Enum SkCanvas::SrcRectConstraint + +
+enum SrcRectConstraint {
+kStrict SrcRectConstraint, 
+kFast SrcRectConstraint, 
+};
+ +SrcRectConstraint controls the behavior at the edge of the Rect src, provided to drawImageRect, +trading off speed for precision. + +Image Filter in Paint may sample multiple pixels in the image. +Rect src restricts the bounds of pixels that may be read. Image Filter may slow +down if it cannot read outside the bounds, when sampling near the edge of Rect src. +SrcRectConstraint specifies whether an Image Filter is allowed to read pixels +outside Rect src. + +### Constants + + + + + + + + +
SkCanvas::kStrict_SrcRectConstraint Requires Image_Filter to respect Rect src,sampling only inside of its bounds, possibly with a performance penalty.
SkCanvas::kFast_SrcRectConstraint Permits Image_Filter to sample outside of Rect srcby half the width of Image Filter, permitting it to run faster but with +error at the image edges.
+ +### Example + +
redBorder contains a black and white checkerboard bordered by red. +redBorder is drawn scaled by 16 on the left. +The middle and right bitmaps are filtered checkboards. +Drawing the checkerboard with kStrict SrcRectConstraint shows only a blur of black and white. +Drawing the checkerboard with kFast SrcRectConstraint allows red to bleed in the corners.
+ + + + +## drawImageRect + +
+void drawImageRect(const SkImage* image, const SkRect& src, const SkRect& dst,
+                   const SkPaint* paint,
+                   SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw Rect src of Image image, scaled and translated to fill Rect dst. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + + +
image +Image containing pixels, dimensions, and format.
src +Source Rect of image to draw from.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
The left bitmap draws with Paint default kNone SkFilterQuality, and stays within +its bounds; there's no bleeding with kFast SrcRectConstraint. +the middle and right bitmaps draw with kLow SkFilterQuality; with +kStrict SrcRectConstraint, the filter remains within the checkerboard, and +with kFast SrcRectConstraint red bleeds on the edges.
+ +--- + +
+void drawImageRect(const SkImage* image, const SkIRect& isrc, const SkRect& dst,
+                   const SkPaint* paint,
+                   SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw IRect isrc of Image image, scaled and translated to fill Rect dst. +Note that isrc is on integer pixel boundaries; dst may include fractional boundaries. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + + +
image +Image containing pixels, dimensions, and format.
isrc +Source IRect of image to draw from.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + +
+void drawImageRect(const SkImage* image, const SkRect& dst, const SkPaint* paint,
+                   SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw Image image, scaled and translated to fill Rect dst, +using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. +Use constaint to choose kStrict SrcRectConstraint or kFast SrcRectConstraint. + +### Parameters + + + + + + +
image +Image containing pixels, dimensions, and format.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + +
+void drawImageRect(const sk_sp& image, const SkRect& src,
+                   const SkRect& dst, const SkPaint* paint,
+                   SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw Rect src of Image image, scaled and translated to fill Rect dst. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + + +
image +Image containing pixels, dimensions, and format.
src +Source Rect of image to draw from.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
Canvas scales and translates; transformation from src to dst also scales. +The two matrices are concatenated to create the final transformation.
+ +--- + +
+void drawImageRect(const sk_sp& image, const SkIRect& isrc,
+                   const SkRect& dst, const SkPaint* paint,
+                   SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw IRect isrc of Image image, scaled and translated to fill Rect dst. +Note that isrc is on integer pixel boundaries; dst may include fractional boundaries. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. +cons set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + + +
image +Image containing pixels, dimensions, and format.
isrc +Source IRect of image to draw from.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + +
+void drawImageRect(const sk_sp& image, const SkRect& dst,
+                   const SkPaint* paint,
+                   SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw Image image, scaled and translated to fill Rect dst, +using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkImage::makeShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + +
image +Image containing pixels, dimensions, and format.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + + +## drawImageNine + +
+void drawImageNine(const SkImage* image, const SkIRect& center,
+                   const SkRect& dst, const SkPaint* paint = nullptr)
+
+ +Draw Image image stretched differentially to fit into Rect dst. +IRect center divides the image into nine sections: four sides, four corners, and the center. +corners are unscaled or scaled down proportionately if their sides are larger than dst; +center and four sides are scaled to fit remaining space, if any. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
image +Image containing pixels, dimensions, and format.
center +IRect edge of image corners and sides.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
The leftmost image is smaller than center; only corners are drawn, all scaled to fit. +The second image equals the size of center; only corners are drawn, unscaled. +The remaining images are larger than center. All corners draw unscaled. The sides +and center are scaled if needed to take up the remaining space.
+ +--- + +
+void drawImageNine(const sk_sp& image, const SkIRect& center,
+                   const SkRect& dst, const SkPaint* paint = nullptr)
+
+ +Draw Image image stretched differentially to fit into Rect dst. +IRect center divides the image into nine sections: four sides, four corners, and the center. +corners are unscaled or scaled down proportionately if their sides are larger than dst; +center and four sides are scaled to fit remaining space, if any. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
image +Image containing pixels, dimensions, and format.
center +IRect edge of image corners and sides.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
The two leftmost images has four corners and sides to the left and right of center. +The leftmost image scales the width of corners proportionately to fit. +The third and fourth image corners are unscaled; the sides and center are scaled to +fill the remaining space. +The rightmost image has four corners scaled vertically to fit, and uses sides above +and below center to fill the remaining space.
+ +--- + + +## drawBitmap + +
+void drawBitmap(const SkBitmap& bitmap, SkScalar left, SkScalar top,
+                const SkPaint* paint = NULL)
+
+ +Draw Bitmap bitmap, with its top-left corner at (left, top), +using Clip, Matrix, and optional Paint paint. +If paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If bitmap is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from bitmap bounds. If generated mask extends +beyond bitmap bounds, replicate bitmap edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the bitmap's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
bitmap +Bitmap containing pixels, dimensions, and format.
left +Left side of bitmap.
top +Top side of bitmap.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
+ +--- + + +## drawBitmapRect + +
+void drawBitmapRect(const SkBitmap& bitmap, const SkRect& src, const SkRect& dst,
+                    const SkPaint* paint,
+                    SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw Rect src of Bitmap bitmap, scaled and translated to fill Rect dst. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If bitmap is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from bitmap bounds. If generated mask extends +beyond bitmap bounds, replicate bitmap edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the bitmap's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + + +
bitmap +Bitmap containing pixels, dimensions, and format.
src +Source Rect of image to draw from.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + +
+void drawBitmapRect(const SkBitmap& bitmap, const SkIRect& isrc,
+                    const SkRect& dst, const SkPaint* paint,
+                    SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw IRect isrc of Bitmap bitmap, scaled and translated to fill Rect dst. +Note that isrc is on integer pixel boundaries; dst may include fractional boundaries. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If bitmap is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from bitmap bounds. If generated mask extends +beyond bitmap bounds, replicate bitmap edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the bitmap's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + + +
bitmap +Bitmap containing pixels, dimensions, and format.
isrc +Source IRect of image to draw from.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + +
+void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst,
+                    const SkPaint* paint,
+                    SrcRectConstraint constraint = kStrict_SrcRectConstraint)
+
+ +Draw Bitmap bitmap, scaled and translated to fill Rect dst. +Note that isrc is on integer pixel boundaries; dst may include fractional boundaries. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If bitmap is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from bitmap bounds. If generated mask extends +beyond bitmap bounds, replicate bitmap edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the bitmap's edge +color when it samples outside of its bounds. +constraint set to kStrict SrcRectConstraint limits Paint Filter Quality to sample within src; +set to kFast SrcRectConstraint allows sampling outside to improve performance. + +### Parameters + + + + + + +
bitmap +Bitmap containing pixels, dimensions, and format.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
constraint +Filter strictly within src or draw faster.
+ +### Example + +
+ +--- + + +## drawBitmapNine + +
+void drawBitmapNine(const SkBitmap& bitmap, const SkIRect& center,
+                    const SkRect& dst, const SkPaint* paint = NULL)
+
+ +Draw Bitmap bitmap stretched differentially to fit into Rect dst. +IRect center divides the bitmap into nine sections: four sides, four corners, and the center. +corners are unscaled or scaled down proportionately if their sides are larger than dst; +center and four sides are scaled to fit remaining space, if any. +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If bitmap is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from bitmap bounds. If generated mask extends +beyond bitmap bounds, replicate bitmap edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the bitmap's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
bitmap +Bitmap containing pixels, dimensions, and format.
center +IRect edge of image corners and sides.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
The two leftmost bitmap draws has four corners and sides to the left and right of center. +The leftmost bitmap draw scales the width of corners proportionately to fit. +The third and fourth draw corners are unscaled; the sides and center are scaled to +fill the remaining space. +The rightmost bitmap draw has four corners scaled vertically to fit, and uses sides above +and below center to fill the remaining space.
+ +--- + +# Struct SkCanvas::Lattice +Lattice divides Bitmap or Image into a rectangular grid. +Grid entries on even columns and even rows are fixed; these entries are +always drawn at their original size if the destination is large enough. +If the destination side is too small to hold the fixed entries, all fixed +entries are proportionately scaled down to fit. +The grid entries not on even columns and rows are scaled to fit the +remaining space, if any. + +
+struct Lattice {
+enum Flags {...
+
+const int*     fXDivs;
+const int*     fYDivs;
+const Flags*   fFlags;
+int            fXCount;
+int            fYCount;
+const SkIRect* fBounds;
+};
+ +## Enum SkCanvas::Lattice::Flags + +
+enum Flags : uint8_t {
+kTransparent Flags = 1 << 0,
+};
+ +Optional setting per rectangular grid entry to make it transparent. + +### Constants + + + + + + +
SkCanvas::Lattice::kTransparent_Flags 1Set to skip lattice rectangle by making it transparent.
+ +const int* fXDivs + +Array of x-coordinates that divide the bitmap vertically. +Array entries must be unique, increasing, greater than or equal to fBounds left edge, +and less than fBounds right edge. +Set the first element to fBounds left to collapse the left column of fixed grid entries. + +const int* fYDivs + +Array of y-coordinates that divide the bitmap horizontally. +Array entries must be unique, increasing, greater than or equal to fBounds top edge, +and less than fBounds bottom edge. +Set the first element to fBounds top to collapse the top row of fixed grid entries. + +const Flags* fFlags + +Optional array of Flags, one per rectangular grid entry: +array length must be (fXCount + 1) * (fYCount + 1). +Array entries correspond to the rectangular grid entries, ascending +left to right and then top to bottom. + +int fXCount + +Number of entries in fXDivs array; one less than the number of horizontal divisions. + +int fYCount + +Number of entries in fYDivs array; one less than the number of vertical divisions. + +const SkIRect* fBounds + +Optional subset IRect source to draw from. +If nullptr, source bounds is dimensions of Bitmap or Image. + + +## drawBitmapLattice + +
+void drawBitmapLattice(const SkBitmap& bitmap, const Lattice& lattice,
+                       const SkRect& dst, const SkPaint* paint = nullptr)
+
+ +Draw Bitmap bitmap stretched differentially to fit into Rect dst. + +Lattice lattice divides bitmap into a rectangular grid. +Each intersection of an even-numbered row and column is fixed; like the corners +of drawBitmapNine, fixed lattice elements never scale larger than their initial size +and shrink proportionately when all fixed elements exceed the bitmap's dimension. +All other grid elements scale to fill the available space, if any. + +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If bitmap is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from bitmap bounds. If generated mask extends +beyond bitmap bounds, replicate bitmap edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the bitmap's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
bitmap +Bitmap containing pixels, dimensions, and format.
lattice +Division of bitmap into fixed and variable rectangles.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
The two leftmost bitmap draws has four corners and sides to the left and right of center. +The leftmost bitmap draw scales the width of corners proportionately to fit. +The third and fourth draw corners are unscaled; the sides are scaled to +fill the remaining space; the center is transparent. +The rightmost bitmap draw has four corners scaled vertically to fit, and uses sides above +and below center to fill the remaining space.
+ +--- + + +## drawImageLattice + +
+void drawImageLattice(const SkImage* image, const Lattice& lattice,
+                      const SkRect& dst, const SkPaint* paint = nullptr)
+
+ +Draw Image image stretched differentially to fit into Rect dst. + +Lattice lattice divides image into a rectangular grid. +Each intersection of an even-numbered row and column is fixed; like the corners +of drawImageNine, fixed lattice elements never scale larger than their initial size +and shrink proportionately when all fixed elements exceed the bitmap's dimension. +All other grid elements scale to fill the available space, if any. + +Additionally transform draw using Clip, Matrix, and optional Paint paint. +If Paint paint is supplied, apply Color Filter, Color Alpha, Image Filter, Blend Mode, and Draw Looper. +If image is kAlpha 8 SkColorType, apply Shader. +if paint contains Mask Filter, generate mask from image bounds. If generated mask extends +beyond image bounds, replicate image edge colors, just as Shader made from +SkShader::MakeBitmapShader with SkShader::kClamp TileMode set replicates the image's edge +color when it samples outside of its bounds. + +### Parameters + + + + + + +
image +Image containing pixels, dimensions, and format.
lattice +Division of bitmap into fixed and variable rectangles.
dst +Destination Rect of image to draw to.
paint +Paint containing Blend Mode, Color Filter, Image Filter, and so on; or nullptr.
+ +### Example + +
The leftmost image is smaller than center; only corners are drawn, all scaled to fit. +The second image equals the size of center; only corners are drawn, unscaled. +The remaining images are larger than center. All corners draw unscaled. The sides +are scaled if needed to take up the remaining space; the center is transparent.
+ +--- + + +## drawText + +
+void drawText(const void* text, size_t byteLength, SkScalar x, SkScalar y,
+              const SkPaint& paint)
+
+ +Draw text, with origin at (x, y), using Clip, Matrix, and Paint paint. +text's meaning depends on Paint Text Encoding; by default, text encoding is UTF-8. +x and y meaning depends on Paint Text Align and Paint Vertical Text; by default text +draws left to right, positioning the first glyph's left side bearing at x and its +baseline at y. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to text. By default, drawText draws filled 12 point black +glyphs. + +### Parameters + + + + + + + +
text +Character code points or glyphs drawn.
byteLength +Byte length of text array.
x +Start of text on x-axis.
y +Start of text on y-axis.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
The same text is drawn varying Paint Text Size and varying +Matrix.
+ +--- + + +## drawString + +
+void drawString(const char* string, SkScalar x, SkScalar y, const SkPaint& paint)
+
+ +Draw null terminated string, with origin at (x, y), using Clip, Matrix, and Paint paint. +string's meaning depends on Paint Text Encoding; by default, string encoding is UTF-8. +Other values of Paint Text Encoding are unlikely to produce the desired results, since +zero bytes may be embedded in the string. +x and y meaning depends on Paint Text Align and Paint Vertical Text; by default string +draws left to right, positioning the first glyph's left side bearing at x and its +baseline at y. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to string. By default, drawString draws filled 12 point black +glyphs. + +### Parameters + + + + + + +
string +Character code points or glyphs drawn, ending with a char value of zero.
x +Start of string on x-axis.
y +Start of string on y-axis.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +### See Also + +drawText + +--- + +
+void drawString(const SkString& string, SkScalar x, SkScalar y,
+                const SkPaint& paint)
+
+ +Draw null terminated string, with origin at (x, y), using Clip, Matrix, and Paint paint. +string's meaning depends on Paint Text Encoding; by default, string encoding is UTF-8. +Other values of Paint Text Encoding are unlikely to produce the desired results, since +zero bytes may be embedded in the string. +x and y meaning depends on Paint Text Align and Paint Vertical Text; by default string +draws left to right, positioning the first glyph's left side bearing at x and its +baseline at y. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to string. By default, drawString draws filled 12 point black +glyphs. + +### Parameters + + + + + + +
string +Character code points or glyphs drawn, ending with a char value of zero.
x +Start of string on x-axis.
y +Start of string on y-axis.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +### See Also + +drawText + +--- + + +## drawPosText + +
+void drawPosText(const void* text, size_t byteLength, const SkPoint pos[],
+                 const SkPaint& paint)
+
+ +Draw each glyph in text with the origin in pos array, using Clip, Matrix, and Paint paint. +The number of entries in pos array must match the number of glyphs described by byteLength of text. +text's meaning depends on Paint Text Encoding; by default, text encoding is UTF-8. +pos elements' meaning depends on Paint Text Align and Paint Vertical Text; by default each +glyph's left side bearing is positioned at x and its +baseline is positioned at y. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to text. By default, drawPosText draws filled 12 point black +glyphs. + +Layout engines such as Harfbuzz typically use drawPosText to position each glyph +rather than using the font's advance widths. + +### Parameters + + + + + + +
text +Character code points or glyphs drawn.
byteLength +Byte length of text array.
pos +Array of glyph origins.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawPosTextH + +
+void drawPosTextH(const void* text, size_t byteLength, const SkScalar xpos[],
+                  SkScalar constY, const SkPaint& paint)
+
+ +Draw each glyph in text with its (x, y) origin composed from xpos array and constY, using Clip, Matrix, and Paint paint. +The number of entries in xpos array must match the number of glyphs described by byteLength of text. +text's meaning depends on Paint Text Encoding; by default, text encoding is UTF-8. +pos elements' meaning depends on Paint Text Align and Paint Vertical Text; by default each +glyph's left side bearing is positioned at an xpos element and its +baseline is positioned at constY. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to text. By default, drawPosTextH draws filled 12 point black +glyphs. + +Layout engines such as Harfbuzz typically use drawPosTextH to position each glyph +rather than using the font's advance widths if all glyphs share the same baseline. + +### Parameters + + + + + + + +
text +Character code points or glyphs drawn.
byteLength +Byte length of text array.
xpos +Array of x positions, used to position each glyph.
constY +Shared y coordinate for all of x positions.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawTextOnPathHV + +
+void drawTextOnPathHV(const void* text, size_t byteLength, const SkPath& path,
+                      SkScalar hOffset, SkScalar vOffset, const SkPaint& paint)
+
+ +Draw text on Path path, using Clip, Matrix, and Paint paint. +Origin of text is at distance hOffset along the path, offset by a perpendicular vector of +length vOffset. If the path section corresponding the glyph advance is curved, the glyph +is drawn curved to match; control points in the glyph are mapped to projected points parallel +to the path. If the text's advance is larger than the path length, the excess text is clipped. + +text's meaning depends on Paint Text Encoding; by default, text encoding is UTF-8. +Origin meaning depends on Paint Text Align and Paint Vertical Text; by default text +positions the first glyph's left side bearing at origin x and its +baseline at origin y. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to text. By default, drawTextOnPathHV draws filled 12 point black +glyphs. + +### Parameters + + + + + + + + +
text +Character code points or glyphs drawn.
byteLength +Byte length of text array.
path +Path providing text baseline.
hOffset +Distance along path to offset origin.
vOffset +Offset of text above (if negative) or below (if positive) the path.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawTextOnPath + +
+void drawTextOnPath(const void* text, size_t byteLength, const SkPath& path,
+                    const SkMatrix* matrix, const SkPaint& paint)
+
+ +Draw text on Path path, using Clip, Matrix, and Paint paint. +Origin of text is at beginning of path offset by matrix, if provided, before it is mapped to path. +If the path section corresponding the glyph advance is curved, the glyph +is drawn curved to match; control points in the glyph are mapped to projected points parallel +to the path. If the text's advance is larger than the path length, the excess text is clipped. + +text's meaning depends on Paint Text Encoding; by default, text encoding is UTF-8. +Origin meaning depends on Paint Text Align and Paint Vertical Text; by default text +positions the first glyph's left side bearing at origin x and its +baseline at origin y. Text size is affected by Matrix and Paint Text Size. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to text. By default, drawTextOnPath draws filled 12 point black +glyphs. + +### Parameters + + + + + + + +
text +Character code points or glyphs drawn.
byteLength +Byte length of text array.
path +Path providing text baseline.
matrix +Optional transform of glyphs before mapping to path; or nullptr.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawTextRSXform + +
+void drawTextRSXform(const void* text, size_t byteLength,
+                     const SkRSXform xform[], const SkRect* cullRect,
+                     const SkPaint& paint)
+
+ +Draw text, transforming each glyph by the corresponding SkRSXform, +using Clip, Matrix, and Paint paint. +RSXform array specifies a separate square scale, rotation, and translation for +each glyph. +Optional Rect cullRect is a conservative bounds of text, +taking into account RSXform and paint. If cullrect is outside of Clip, canvas can +skip drawing. + +All elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to text. By default, drawTextRSXform draws filled 12 point black +glyphs. + +### Parameters + + + + + + + +
text +Character code points or glyphs drawn.
byteLength +Byte length of text array.
xform +RSXform rotates, scales, and translates each glyph individually.
cullRect +Rect bounds of text for efficient clipping; or nullptr.
paint +Text size, blend, color, and so on, used to draw.
+ +### Example + +
+ +--- + + +## drawTextBlob + +
+void drawTextBlob(const SkTextBlob* blob, SkScalar x, SkScalar y,
+                  const SkPaint& paint)
+
+ +Draw Text Blob blob at (x, y), using Clip, Matrix, and Paint paint. +blob contains glyphs, their positions, and paint attributes specific to text: +Typeface, Paint Text Size, Paint Text Scale X, Paint Text Skew X, Paint Text Align, +Paint Hinting, Anti-alias, Paint Fake Bold, Font Embedded Bitmaps, Full Hinting Spacing, +LCD Text, Linear Text, Subpixel Text, and Paint Vertical Text. + +Elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to blob. + +### Parameters + + + + + + +
blob +Glyphs, positions, and their paints' text size, typeface, and so on.
x +Horizontal offset applied to blob.
y +Vertical offset applied to blob.
paint +Blend, color, stroking, and so on, used to draw.
+ +### Example + +
+ +--- + +
+void drawTextBlob(const sk_sp& blob, SkScalar x, SkScalar y,
+                  const SkPaint& paint)
+
+ +Draw Text Blob blob at (x, y), using Clip, Matrix, and Paint paint. +blob contains glyphs, their positions, and paint attributes specific to text: +Typeface, Paint Text Size, Paint Text Scale X, Paint Text Skew X, Paint Text Align, +Paint Hinting, Anti-alias, Paint Fake Bold, Font Embedded Bitmaps, Full Hinting Spacing, +LCD Text, Linear Text, Subpixel Text, and Paint Vertical Text. + +Elements of paint: Path Effect, Rasterizer, Mask Filter, Shader, Color Filter, +Image Filter, and Draw Looper; apply to blob. + +### Parameters + + + + + + +
blob +Glyphs, positions, and their paints' text size, typeface, and so on.
x +Horizontal offset applied to blob.
y +Vertical offset applied to blob.
paint +Blend, color, stroking, and so on, used to draw.
+ +### Example + +
Paint attributes unrelated to text, like color, have no effect on paint in allocated Text Blob. +Paint attributes related to text, like text size, have no effect on paint passed to drawTextBlob.
+ +--- + + +## drawPicture + +
+void drawPicture(const SkPicture* picture)
+
+ +Draw Picture picture, using Clip and Matrix. +Clip and Matrix are unchanged by picture contents, as if +save was called before and restore was called after drawPicture. + +Picture records a series of draw commands for later playback. + +### Parameters + + + +
picture +Recorded drawing commands to play.
+ +### Example + +
+ +--- + +
+void drawPicture(const sk_sp& picture)
+
+ +Draw Picture picture, using Clip and Matrix. +Clip and Matrix are unchanged by picture contents, as if +save was called before and restore was called after drawPicture. + +Picture records a series of draw commands for later playback. + +### Parameters + + + +
picture +Recorded drawing commands to play.
+ +### Example + +
+ +--- + +
+void drawPicture(const SkPicture* picture, const SkMatrix* matrix,
+                 const SkPaint* paint)
+
+ +Draw Picture picture, using Clip and Matrix; +transforming picture with Matrix matrix, if provided; +and use Paint paint Color Alpha, Color Filter, Image Filter, and Blend Mode, if provided. + +matrix transformation is equivalent to: save, concat, drawPicture, restore. +paint use is equivalent to: saveLayer, drawPicture, restore. + +### Parameters + + + + + +
picture +Recorded drawing commands to play.
matrix +Optional Matrix to rotate, scale, translate, and so on; or nullptr.
paint +Optional Paint to apply transparency, filtering, and so on; or nullptr.
+ +### Example + +
+ +--- + +
+void drawPicture(const sk_sp& picture, const SkMatrix* matrix,
+                 const SkPaint* paint)
+
+ +Draw Picture picture, using Clip and Matrix; +transforming picture with Matrix matrix, if provided; +and use Paint paint Color Alpha, Color Filter, Image Filter, and Blend Mode, if provided. + +matrix transformation is equivalent to: save, concat, drawPicture, restore. +paint use is equivalent to: saveLayer, drawPicture, restore. + +### Parameters + + + + + +
picture +Recorded drawing commands to play.
matrix +Optional Matrix to rotate, scale, translate, and so on; or nullptr.
paint +Optional Paint to apply transparency, filtering, and so on; or nullptr.
+ +### Example + +
+ +--- + + +## drawVertices + +
+void drawVertices(const SkVertices* vertices, SkBlendMode mode,
+                  const SkPaint& paint)
+
+ +Draw Vertices vertices, a triangle mesh, using Clip and Matrix. +If Vertices Texs and Vertices Colors are defined in vertices, and Paint paint contains Shader, +Blend Mode mode combines Vertices Colors with Shader. + +### Parameters + + + + + +
vertices +The triangle mesh to draw.
mode +Combines Vertices Colors with Shader, if both are present.
paint +Specifies the Shader, used as Vertices texture, if present.
+ +### Example + +
+ +--- + +
+void drawVertices(const sk_sp& vertices, SkBlendMode mode,
+                  const SkPaint& paint)
+
+ +Draw Vertices vertices, a triangle mesh, using Clip and Matrix. +If Vertices Texs and Vertices Colors are defined in vertices, and Paint paint contains Shader, +Blend Mode mode combines Vertices Colors with Shader. + +### Parameters + + + + + +
vertices +The triangle mesh to draw.
mode +Combines Vertices Colors with Shader, if both are present.
paint +Specifies the Shader, used as Vertices texture, if present.
+ +### Example + +
+ +--- + + +## drawPatch + +
+void drawPatch(const SkPoint cubics[12], const SkColor colors[4],
+               const SkPoint texCoords[4], SkBlendMode mode,
+               const SkPaint& paint)
+
+ +Draw a cubic Coons patch: the interpolation of four cubics with shared corners, +associating a color, and optionally a texture coordinate, with each corner. + +The Coons patch uses Clip and Matrix, Paint paint's Shader, Color Filter, Color Alpha, +Image Filter, and Blend Mode. If Shader is provided it is treated as the Coons +patch texture; Blend Mode mode combines Color colors and Shader if both are provided. + +### Parameters + + + + + + + +
cubics +Point array cubics specifying the four cubics starting at the top left corner,
colors +Color array color associating colors with corners in top left, top right, bottom right,
texCoords +Point array texCoords mapping Shader as texture to corners in same order, if paint
mode +Blend Mode for colors and Shader if present.
paint +Shader, Color Filter, Blend Mode, used to draw.
+ +### Example + +
+ +--- + +
+void drawPatch(const SkPoint cubics[12], const SkColor colors[4],
+               const SkPoint texCoords[4], const SkPaint& paint)
+
+ +Draw a cubic Coons patch: the interpolation of four cubics with shared corners, +associating a color, a texture coordinate, or both, with each corner. + +The Coons patch uses Clip and Matrix, Paint paint's Shader, Color Filter, Color Alpha, +Image Filter, (?) and Blend Mode. If Shader is provided it is treated as the Coons +patch texture. + +### Parameters + + + + + + +
cubics +Point array cubics specifying the four cubics starting at the top left corner,
colors +Color array color associating colors with corners in top left, top right, bottom right,
texCoords +Point array texCoords mapping Shader as texture to corners in same order, if paint
paint +Shader, Color Filter, Blend Mode, used to draw.
+ +### Example + +
+ +### Example + +
+ +--- + + +## drawAtlas + +
+void drawAtlas(const SkImage* atlas, const SkRSXform xform[], const SkRect tex[],
+               const SkColor colors[], int count, SkBlendMode mode,
+               const SkRect* cullRect, const SkPaint* paint)
+
+ +Draw a set of sprites from atlas, using Clip, Matrix, and optional Paint paint. +paint uses Anti-alias, Color Alpha, Color Filter, Image Filter, and Blend Mode to draw, if present. +For each entry in the array, Rect tex locates sprite in atlas, and RSXform xform transforms it +into destination space. +xform, text, and colors if present, must contain count entries. +Optional colors is applied for each sprite using Blend Mode. +Optional cullRect is a conservative bounds of all transformed sprites. +If cullrect is outside of Clip, canvas can skip drawing. + +### Parameters + + + + + + + + + + +
atlas +Image containing sprites.
xform +RSXform mappings for sprites in atlas.
tex +Rect locations of sprites in atlas.
colors +Color, one per sprite, blended with sprite using Blend Mode; or nullptr.
count +Number of sprites to draw.
mode +Blend Mode combining colors and sprites.
cullRect +Rect bounds of transformed sprites for efficient clipping; or nullptr.
paint +Paint Color Filter, Image Filter, Blend Mode, and so on; or nullptr.
+ +### Example + +
+ +--- + +
+void drawAtlas(const sk_sp& atlas, const SkRSXform xform[],
+               const SkRect tex[], const SkColor colors[], int count,
+               SkBlendMode mode, const SkRect* cullRect, const SkPaint* paint)
+
+ +Draw a set of sprites from atlas, using Clip, Matrix, and optional Paint paint. +paint uses Anti-alias, Color Alpha, Color Filter, Image Filter, and Blend Mode to draw, if present. +For each entry in the array, Rect tex locates sprite in atlas, and RSXform xform transforms it +into destination space. +xform, text, and colors if present, must contain count entries. +Optional colors is applied for each sprite using Blend Mode. +Optional cullRect is a conservative bounds of all transformed sprites. +If cullrect is outside of Clip, canvas can skip drawing. + +### Parameters + + + + + + + + + + +
atlas +Image containing sprites.
xform +RSXform mappings for sprites in atlas.
tex +Rect locations of sprites in atlas.
colors +Color, one per sprite, blended with sprite using Blend Mode; or nullptr.
count +Number of sprites to draw.
mode +Blend Mode combining colors and sprites.
cullRect +Rect bounds of transformed sprites for efficient clipping; or nullptr.
paint +Paint Color Filter, Image Filter, Blend Mode, and so on; or nullptr.
+ +### Example + +
+ +--- + +
+void drawAtlas(const SkImage* atlas, const SkRSXform xform[], const SkRect tex[],
+               int count, const SkRect* cullRect, const SkPaint* paint)
+
+ +Draw a set of sprites from atlas, using Clip, Matrix, and optional Paint paint. +paint uses Anti-alias, Color Alpha, Color Filter, Image Filter, and Blend Mode to draw, if present. +For each entry in the array, Rect tex locates sprite in atlas, and RSXform xform transforms it +into destination space. +xform and text must contain count entries. +Optional cullRect is a conservative bounds of all transformed sprites. +If cullrect is outside of Clip, canvas can skip drawing. + +### Parameters + + + + + + + + +
atlas +Image containing sprites.
xform +RSXform mappings for sprites in atlas.
tex +Rect locations of sprites in atlas.
count +Number of sprites to draw.
cullRect +Rect bounds of transformed sprites for efficient clipping; or nullptr.
paint +Paint Color Filter, Image Filter, Blend Mode, and so on; or nullptr.
+ +### Example + +
+ +--- + +
+void drawAtlas(const sk_sp& atlas, const SkRSXform xform[],
+               const SkRect tex[], int count, const SkRect* cullRect,
+               const SkPaint* paint)
+
+ +Draw a set of sprites from atlas, using Clip, Matrix, and optional Paint paint. +paint uses Anti-alias, Color Alpha, Color Filter, Image Filter, and Blend Mode to draw, if present. +For each entry in the array, Rect tex locates sprite in atlas, and RSXform xform transforms it +into destination space. +xform and text must contain count entries. +Optional cullRect is a conservative bounds of all transformed sprites. +If cullrect is outside of Clip, canvas can skip drawing. + +### Parameters + + + + + + + + +
atlas +Image containing sprites.
xform +RSXform mappings for sprites in atlas.
tex +Rect locations of sprites in atlas.
count +Number of sprites to draw.
cullRect +Rect bounds of transformed sprites for efficient clipping; or nullptr.
paint +Paint Color Filter, Image Filter, Blend Mode, and so on; or nullptr.
+ +### Example + +
+ +--- + + +## drawDrawable + +
+void drawDrawable(SkDrawable* drawable, const SkMatrix* matrix = NULL)
+
+ +Draw Drawable drawable using Clip and Matrix, concatenated with +optional matrix. + +If Canvas has an asynchronous implementation, as is the case +when it is recording into Picture, then drawable will be referenced, +so that SkDrawable::draw() can be called when the operation is finalized. To force +immediate drawing, call SkDrawable::draw() instead. + +### Parameters + + + + +
drawable +Custom struct encapsulating drawing commands.
matrix +Transformation applied to drawing; or nullptr.
+ +### Example + +
+ +--- + +
+void drawDrawable(SkDrawable* drawable, SkScalar x, SkScalar y)
+
+ +Draw Drawable drawable using Clip and Matrix, offset by (x, y). + +If Canvas has an asynchronous implementation, as is the case +when it is recording into Picture, then drawable will be referenced, +so that SkDrawable::draw() can be called when the operation is finalized. To force +immediate drawing, call SkDrawable::draw() instead. + +### Parameters + + + + + +
drawable +Custom struct encapsulating drawing commands.
x +Offset into Canvas writable pixels in x.
y +Offset into Canvas writable pixels in y.
+ +### Example + +
+ +--- + + +## drawAnnotation + +
+void drawAnnotation(const SkRect& rect, const char key[], SkData* value)
+
+ +Associate Rect on Canvas when an annotation; a key-value pair, where the key is +a null-terminated utf8 string, and optional value is stored as Data. + +Only some canvas implementations, such as recording to Picture, or drawing to +Document PDF, use annotations. + +### Parameters + + + + + +
rect +Rect extent of canvas to annotate.
key +String used for lookup.
value +Data holding value stored in annotation.
+ +### Example + +
+ +--- + +
+void drawAnnotation(const SkRect& rect, const char key[],
+                    const sk_sp& value)
+
+ +Associate Rect on Canvas when an annotation; a key-value pair, where the key is +a null-terminated utf8 string, and optional value is stored as Data. + +Only some canvas implementations, such as recording to Picture, or drawing to +Document PDF, use annotations. + +### Parameters + + + + + +
rect +Rect extent of canvas to annotate.
key +String used for lookup.
value +Data holding value stored in annotation.
+ +### Example + +
+ +--- + + +## getDrawFilter + +
+SkDrawFilter* getDrawFilter() const
+
+ +Legacy call to be deprecated. + +--- + + +## setDrawFilter + +
+virtual SkDrawFilter* setDrawFilter(SkDrawFilter* filter)
+
+ +Legacy call to be deprecated. + +--- + + +## isClipEmpty + +
+virtual bool isClipEmpty() const
+
+ +Returns true if Clip is empty; that is, nothing will draw. + +isClipEmpty may do work when called; it should not be called +more often than needed. However, once called, subsequent calls perform no +work until Clip changes. + +### Return Value + +true if Clip is empty. + +### Example + +
+ +#### Example Output + +~~~~ +clip is not empty +clip is empty +~~~~ + +
+ +--- + + +## isClipRect + +
+virtual bool isClipRect() const
+
+ +Returns true if Clip is Rect and not empty. +Returns false if the clip is empty, or if it is not Rect. + +### Return Value + +true if Clip is Rect and not empty. + +### Example + +
+ +#### Example Output + +~~~~ +clip is rect +clip is not rect +~~~~ + +
+ +--- + diff --git a/site/user/api/SkPaint_Reference.md b/site/user/api/SkPaint_Reference.md new file mode 100644 index 0000000000..ae938fbffe --- /dev/null +++ b/site/user/api/SkPaint_Reference.md @@ -0,0 +1,5190 @@ +SkPaint Reference +=== + +# Paint +Paint controls options applied when drawing and measuring. Paint collects all +options outside of the Canvas Clip and Canvas Matrix. + +Various options apply to text, strokes and fills, and images. + +Some options may not be implemented on all platforms; in these cases, setting +the option has no effect. Some options are conveniences that duplicate Canvas +functionality; for instance, text size is identical to matrix scale. + +Paint options are rarely exclusive; each option modifies a stage of the drawing +pipeline and multiple pipeline stages may be affected by a single Paint. + +Paint collects effects and filters that describe single-pass and multiple-pass +algorithms that alter the drawing geometry, color, and transparency. For instance, +Paint does not directly implement dashing or blur, but contains the objects that do so. + +The objects contained by Paint are opaque, and cannot be edited outside of the Paint +to affect it. The implementation is free to defer computations associated with the +Paint, or ignore them altogether. For instance, some GPU implementations draw all +Path geometries with anti-aliasing, regardless of SkPaint::kAntiAlias Flag setting. + +Paint describes a single color, a single font, a single image quality, and so on. +Multiple colors are drawn either by using multiple paints or with objects like +Shader attached to Paint. + +# Class SkPaint + +# Overview + +## Subtopics + +| topics | description | +| --- | --- | +| Initializers | Constructors and initialization. | +| Destructor | Paint termination. | +| Management | Paint copying, moving, comparing. | +| Hinting | Glyph outline adjustment. | +| Flags | Attributes represented by single bits. | +| Anti-alias | Approximating coverage with transparency. | +| Dither | Distributing color error. | +| Device Text | Increase precision of glyph position. | +| Font Embedded Bitmaps | Custom-sized bitmap glyphs. | +| Automatic Hinting | Always adjust glyph paths. | +| Vertical Text | Orient text from top to bottom. | +| Fake Bold | Approximate font styles. | +| Full Hinting Spacing | Glyph spacing affected by hinting. | +| Filter Quality Methods | Get and set Filter Quality. | +| Color Methods | Get and set Color. | +| Style | Geometry filling, stroking. | +| Stroke Width | Thickness perpendicular to geometry. | +| Miter Limit | Maximum length of stroked corners. | +| Stroke Cap | Decorations at ends of open strokes. | +| Stroke Join | Decoration at corners of strokes. | +| Fill Path | Make Path from Path Effect, stroking. | +| Shader Methods | Get and set Shader. | +| Color Filter Methods | Get and set Color Filter. | +| Blend Mode Methods | Get and set Blend Mode. | +| Path Effect Methods | Get and set Path Effect. | +| Mask Filter Methods | Get and set Mask Filter. | +| Typeface Methods | Get and set Typeface. | +| Rasterizer Methods | Get and set Rasterizer. | +| Image Filter Methods | Get and set Image Filter. | +| Draw Looper Methods | Get and set Draw Looper. | +| Text Align | Text placement relative to position. | +| Text Size | Overall height in points. | +| Text Scale X | Text horizontal scale. | +| Text Skew X | Text horizontal slant. | +| Text Encoding | Text encoded as characters or glyphs. | +| Font Metrics | Common glyph dimensions. | +| Measure Text | Width, height, bounds of text. | +| Text Path | Geometry of glyphs. | +| Text Intercepts | Advanced underline, strike through. | +| Fast Bounds | Appproxiate area required by Paint. | + +## Constants + +| constants | description | +| --- | --- | +| Align | Glyph locations relative to text position. | +| Cap | Start and end geometry on stroked shapes. | +| Flags | Values described by bits and masks. | +| FontMetrics::FontMetricsFlags | Valid Font Metrics. | +| Hinting | Level of glyph outline adjustment. | +| Join | Corner geometry on stroked shapes. | +| Style | Stroke, fill, or both. | +| TextEncoding | Character or glyph encoding size. | + +## Structs + +| struct | description | +| --- | --- | +| FontMetrics | Typeface values. | + +## Constructors + +| | description | +| --- | --- | +| SkPaint() | Constructs with default values. | +| SkPaint(const SkPaint& paint) | Makes a shallow copy. | +| SkPaint(SkPaint&& paint) | Moves paint without copying it. | +| | Decreases Reference Count of owned objects. | + +## Operators + +| operator | description | +| --- | --- | +| operator=(const SkPaint& paint) | Makes a shallow copy. | +| operator=(SkPaint&& paint) | Moves paint without copying it. | +| operator==(const SkPaint& a, const SkPaint& b) | Compares paints for equality. | +| operator!=(const SkPaint& a, const SkPaint& b) | Compares paints for inequality. | + +## Member Functions + +| function | description | +| --- | --- | +| breakText | Returns text that fits in a width. | +| canComputeFastBounds | Returns true if settings allow for fast bounds computation. | +| computeFastBounds | Returns fill bounds for quick reject tests. | +| computeFastStrokeBounds | Returns stroke bounds for quick reject tests. | +| containsText | Returns if all text corresponds to glyphs. | +| countText | Returns number of glyphs in text. | +| doComputeFastBounds | Returns bounds for quick reject tests. | +| flatten | Serializes into a buffer. | +| getAlpha | Returns Color Alpha, color opacity. | +| getBlendMode | Returns Blend Mode, how colors combine with dest. | +| getColor | Returns Color Alpha and Color RGB, one drawing color. | +| getColorFilter | Returns Color Filter, how colors are altered. | +| getDrawLooper | Returns Draw Looper, multiple layers. | +| getFillPath | Returns fill path equivalent to stroke. | +| getFilterQuality | Returns Filter Quality, image filtering level. | +| getFlags | Returns Flags stored in a bit field. | +| getFontBounds | Returns union all glyph bounds. | +| getFontMetrics | Returns Typeface metrics scaled by text size. | +| getFontSpacing | Returns recommended spacing between lines. | +| getHash | Returns a shallow hash for equality checks. | +| getHinting | Returns Hinting, glyph outline adjustment level. | +| getImageFilter | Returns Image Filter, alter pixels; blur. | +| getMaskFilter | Returns Mask Filter, alterations to Mask Alpha. | +| getPathEffect | Returns Path Effect, modifications to path geometry; dashing. | +| getPosTextPath | Returns Path equivalent to positioned text. | +| getPosTextIntercepts | Returns where lines intersect positioned text; underlines. | +| getPosTextHIntercepts | Returns where lines intersect horizontally positioned text; underlines. | +| getRasterizer | Returns Rasterizer, Mask Alpha generation from Path. | +| getShader | Returns Shader, multiple drawing colors; gradients. | +| getStrokeCap | Returns Cap, the area drawn at path ends. | +| getStrokeJoin | Returns Join, geometry on path corners. | +| getStrokeMiter | Returns Miter Limit, angles with sharp corners. | +| getStrokeWidth | Returns thickness of the stroke. | +| getStyle | Returns Style: stroke, fill, or both. | +| getTextAlign | Returns Align: left, center, or right. | +| getTextBlobIntercepts | Returns where lines intersect Text Blob; underlines. | +| getTextEncoding | Returns character or glyph encoding size. | +| getTextIntercepts | Returns where lines intersect text; underlines. | +| getTextPath | Returns Path equivalent to text. | +| getTextScaleX | Returns the text horizontal scale; condensed text. | +| getTextSkewX | Returns the text horizontal skew; oblique text. | +| getTextSize | Returns text size in points. | +| getTextWidths | Returns advance and bounds for each glyph in text. | +| getTypeface | Returns Typeface, font description. | +| glyphsToUnichars | Converts glyphs into text. | +| isAntiAlias | Returns true if Anti-alias is set. | +| isAutohinted | Returns true if glyphs are always hinted. | +| isDevKernText | Returns true if Full Hinting Spacing is set. | +| isDither | Returns true if Dither is set. | +| isEmbeddedBitmapText | Returns true if Font Embedded Bitmaps is set. | +| isFakeBoldText | Returns true if Fake Bold is set. | +| isLCDRenderText | Returns true if LCD Text is set. | +| isSrcOver | Returns true if Blend Mode is SkBlendMode::kSrcOver. | +| isSubpixelText | Returns true if Subpixel Text is set. | +| isVerticalText | Returns true if Vertical Text is set. | +| measureText | Returns advance width and bounds of text. | +| nothingToDraw | Returns true if Paint prevents all drawing. | +| refColorFilter | References Color Filter, how colors are altered. | +| refDrawLooper | References Draw Looper, multiple layers. | +| refImageFilter | References Image Filter, alter pixels; blur. | +| refMaskFilter | References Mask Filter, alterations to Mask Alpha. | +| refPathEffect | References Path Effect, modifications to path geometry; dashing. | +| refRasterizer | References Rasterizer, mask generation from path. | +| refShader | References Shader, multiple drawing colors; gradients. | +| refTypeface | References Typeface, font description. | +| reset | Sets to default values. | +| setAlpha | Sets Color Alpha, color opacity. | +| setAntiAlias | Sets or clears Anti-alias. | +| setARGB | Sets color by component. | +| setAutohinted | Sets glyphs to always be hinted. | +| setBlendMode | Sets Blend Mode, how colors combine with destination. | +| setColor | Sets Color Alpha and Color RGB, one drawing color. | +| setColorFilter | Sets Color Filter, alters color. | +| setDevKernText | Sets or clears Full Hinting Spacing. | +| setDither | Sets or clears Dither. | +| setDrawLooper | Sets Draw Looper, multiple layers. | +| setEmbeddedBitmapText | Sets or clears Font Embedded Bitmaps. | +| setFakeBoldText | Sets or clears Fake Bold. | +| setFilterQuality | Sets Filter Quality, the image filtering level. | +| setFlags | Sets multiple Flags in a bit field. | +| setHinting | Sets Hinting, glyph outline adjustment level. | +| setLCDRenderText | Sets or clears LCD Text. | +| setMaskFilter | Sets Mask Filter, alterations to Mask Alpha. | +| setPathEffect | Sets Path Effect, modifications to path geometry; dashing. | +| setRasterizer | Sets Rasterizer, Mask Alpha generation from Path. | +| setImageFilter | Sets Image Filter, alter pixels; blur. | +| setShader | Sets Shader, multiple drawing colors; gradients. | +| setStrokeCap | Sets Cap, the area drawn at path ends. | +| setStrokeJoin | Sets Join, geometry on path corners. | +| setStrokeMiter | Sets Miter Limit, angles with sharp corners. | +| setStrokeWidth | Sets thickness of the stroke. | +| setStyle | Sets Style: stroke, fill, or both. | +| setSubpixelText | Sets or clears Subpixel Text. | +| setTextAlign | Sets Align: left, center, or right. | +| setTextEncoding | Sets character or glyph encoding size. | +| setTextScaleX | Sets the text horizontal scale; condensed text. | +| setTextSkewX | Sets the text horizontal skew; oblique text. | +| setTextSize | Sets text size in points. | +| setTypeface | Sets Typeface, font description. | +| setVerticalText | Sets or clears Vertical Text. | +| textToGlyphs | Converts text into glyph indices. | +| toString | Converts Paint to machine parsable form (Developer Mode) | +| unflatten | Populates from a serialized stream. | + +# Initializers + + +## SkPaint + +
+SkPaint()
+
+ +Constructs Paint with default values. + +| attribute | default value | +| --- | --- | +| Anti-alias | false | +| Blend Mode | SkBlendMode::kSrcOver | +| Color | SK ColorBLACK | +| Color Alpha | 255 | +| Color Filter | nullptr | +| Dither | false | +| Draw Looper | nullptr | +| Fake Bold | false | +| Filter Quality | kNone SkFilterQuality | +| Font Embedded Bitmaps | false | +| Automatic Hinting | false | +| Full Hinting Spacing | false | +| Hinting | kNormal Hinting | +| Image Filter | nullptr | +| LCD Text | false | +| Linear Text | false | +| Miter Limit | 4 | +| Mask Filter | nullptr | +| Path Effect | nullptr | +| Rasterizer | nullptr | +| Shader | nullptr | +| Style | kFill Style | +| Text Align | kLeft Align | +| Text Encoding | kUTF8 TextEncoding | +| Text Scale X | 1 | +| Text Size | 12 | +| Text Skew X | 0 | +| Typeface | nullptr | +| Stroke Cap | kButt Cap | +| Stroke Join | kMiter Join | +| Stroke Width | 0 | +| Subpixel Text | false | +| Vertical Text | false | + +The flags, text size, hinting, and miter limit may be overridden at compile time by defining +paint default values. The overrides may be included in SkUserConfig.h or predefined by the +build system. + +### Return Value + +default initialized Paint + +### Example + +
+ +--- + + +## SkPaint + +
+SkPaint(const SkPaint& paint)
+
+ +Makes a shallow copy of Paint. Typeface, Path Effect, Shader, +Mask Filter, Color Filter, Rasterizer, Draw Looper, and Image Filter are shared +between the original paint and the copy. These objects' Reference Count are increased. + +The referenced objects Path Effect, Shader, Mask Filter, Color Filter, Rasterizer, +Draw Looper, and Image Filter cannot be modified after they are created. +This prevents objects with Reference Count from being modified once Paint refers to them. + +### Parameters + + + +
paint +original to copy
+ +### Return Value + +shallow copy of paint + +### Example + +
+ +#### Example Output + +~~~~ +SK_ColorRED == paint1.getColor() +SK_ColorBLUE == paint2.getColor() +~~~~ + +
+ +--- + + +## SkPaint + +
+SkPaint(SkPaint&& paint)
+
+ +Implements a move constructor to avoid incrementing the reference counts +of objects referenced by the paint. + +After the call, paint is undefined, and can be safely destructed. + +### Parameters + + + +
paint +original to move
+ +### Return Value + +content of paint + +### Example + +
+ +#### Example Output + +~~~~ +path effect unique: true +~~~~ + +
+ +--- + + +## reset + +
+void reset()
+
+ +Sets all paint's contents to their initial values. This is equivalent to replacing +the paint with the result of SkPaint(). + +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Destructor + + +## ~SkPaint + +
+~SkPaint()
+
+ +Decreases Paint Reference Count of owned objects: Typeface, Path Effect, Shader, +Mask Filter, Color Filter, Rasterizer, Draw Looper, and Image Filter. If the +objects' reference count goes to zero, they are deleted. + +--- + +# Management + + +## operator= + +
+SkPaint& operator=(const SkPaint& paint)
+
+ +Makes a shallow copy of Paint. Typeface, Path Effect, Shader, +Mask Filter, Color Filter, Rasterizer, Draw Looper, and Image Filter are shared +between the original paint and the copy. The objects' Reference Count are in the +prior destination are decreased by one, and the referenced objects are deleted if the +resulting count is zero. The objects' Reference Count in the parameter paint are increased +by one. paint is unmodified. + +### Parameters + + + +
paint +original to copy
+ +### Return Value + +content of paint + +### Example + +
+ +#### Example Output + +~~~~ +SK_ColorRED == paint1.getColor() +SK_ColorRED == paint2.getColor() +~~~~ + +
+ +--- + + +## operator= + +
+SkPaint& operator=(SkPaint&& paint)
+
+ +Moves the paint to avoid incrementing the reference counts +of objects referenced by the paint parameter. The objects' Reference Count are in the +prior destination are decreased by one, and the referenced objects are deleted if the +resulting count is zero. + +After the call, paint is undefined, and can be safely destructed. + +### Parameters + + + +
paint +original to move
+ +### Return Value + +content of paint + +### Example + +
+ +#### Example Output + +~~~~ +SK_ColorRED == paint2.getColor() +~~~~ + +
+ +--- + + +## operator== + +
+bool operator==(const SkPaint& a, const SkPaint& b)
+
+ +Compares a and b, and returns true if a and b are equivalent. May return false +if Typeface, Path Effect, Shader, Mask Filter, Color Filter, Rasterizer, +Draw Looper, or Image Filter have identical contents but different pointers. + +### Parameters + + + + +
a +Paint to compare
b +Paint to compare
+ +### Return Value + +true if Paint pair are equivalent + +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +paint1 != paint2 +~~~~ + +
+ +--- + + +## operator!= + +
+bool operator!=(const SkPaint& a, const SkPaint& b)
+
+ +Compares a and b, and returns true if a and b are not equivalent. May return true +if Typeface, Path Effect, Shader, Mask Filter, Color Filter, Rasterizer, +Draw Looper, or Image Filter have identical contents but different pointers. + +### Parameters + + + + +
a +Paint to compare
b +Paint to compare
+ +### Return Value + +true if Paint pair are not equivalent + +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +paint1 == paint2 +~~~~ + +
+ +--- + + +## getHash + +
+uint32_t getHash() const
+
+ +Returns a hash generated from Paint values and pointers. +Identical hashes guarantee that the paints are +equivalent, but differing hashes do not guarantee that the paints have differing +contents. + +If operator==(const SkPaint& a, const SkPaint& b) returns true for two paints, +their hashes are also equal. + +The hash returned is platform and implementation specific. + +### Return Value + +a shallow hash + +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +paint1.getHash() == paint2.getHash() +~~~~ + +
+ +--- + + +## flatten + +
+void flatten(SkWriteBuffer& buffer) const
+
+ +Serializes Paint into a buffer. A companion unflatten call +can reconstitute the paint at a later time. + +### Parameters + + + +
buffer +Write Buffer receiving the flattened Paint data
+ +### Example + +
+ +#### Example Output + +~~~~ +color = 0xffff0000 +~~~~ + +
+ +--- + + +## unflatten + +
+void unflatten(SkReadBuffer& buffer)
+
+ +Populates Paint, typically from a serialized stream, created by calling +flatten at an earlier time. + +SkReadBuffer class is not public, so unflatten cannot be meaningfully called +by the client. + +### Parameters + + + +
buffer +serialized data to unflatten
+ +--- + +# Hinting + +## Enum SkPaint::Hinting + +
+enum Hinting {
+kNo Hinting            = 0,
+kSlight Hinting        = 1,
+kNormal Hinting        = 2,
+kFull Hinting          = 3
+};
+ +Hinting adjusts the glyph outlines so that the shape provides a uniform +look at a given point size on font engines that support it. Hinting may have a +muted effect or no effect at all depending on the platform. + +The four levels roughly control corresponding features on platforms that use FreeType +as the Font Engine. + +### Constants + + + + + + + + + + + + + + +
SkPaint::kNo_Hinting 0Leaves glyph outlines unchanged from their native representation. +With FreeType, this is equivalent to the FT LOAD NO HINTING +bit-field constant supplied to FT Load Glyph, which indicates that the vector +outline being loaded should not be fitted to the pixel grid but simply scaled +to 26.6 fractional pixels.
SkPaint::kSlight_Hinting 1Modifies glyph outlines minimally to improve constrast. +With FreeType, this is equivalent in spirit to the +FT LOAD TARGET LIGHT value supplied to FT Load Glyph. It chooses a +lighter hinting algorithm for non-monochrome modes. +Generated glyphs may be fuzzy but better resemble their original shape.
SkPaint::kNormal_Hinting 2Modifies glyph outlines to improve constrast. This is the default. +With FreeType, this supplies FT LOAD TARGET NORMAL to FT Load Glyph, +choosing the default hinting algorithm, which is optimized for standard +gray-level rendering.
SkPaint::kFull_Hinting 3Modifies glyph outlines for maxiumum constrast. With FreeType, this selects +FT LOAD TARGET LCD or FT LOAD TARGET LCD V if kLCDRenderText Flag is set. +FT LOAD TARGET LCD is a variant of FT LOAD TARGET NORMAL optimized for +horizontally decimated LCD displays; FT LOAD TARGET LCD V is a +variant of FT LOAD TARGET NORMAL optimized for vertically decimated LCD displays.
+ +On Windows with DirectWrite, Hinting has no effect. + +Hinting defaults to kNormal Hinting. +Set SkPaintDefaults Hinting at compile time to change the default setting. + + + + +## getHinting + +
+Hinting getHinting() const
+
+ +Returns level of glyph outline adjustment. + +### Return Value + +one of: kNo Hinting, kSlight Hinting, kNormal Hinting, kFull Hinting + +### Example + +
+ +#### Example Output + +~~~~ +SkPaint::kNormal_Hinting == paint.getHinting() +~~~~ + +
+ +--- + + +## setHinting + +
+void setHinting(Hinting hintingLevel)
+
+ +Sets level of glyph outline adjustment. +Does not check for valid values of hintingLevel. + +| Hinting | value | effect on generated glyph outlines | +| --- | --- | --- | +| kNo Hinting | 0 | leaves glyph outlines unchanged from their native representation | +| kSlight Hinting | 1 | modifies glyph outlines minimally to improve constrast | +| kNormal Hinting | 2 | modifies glyph outlines to improve constrast | +| kFull Hinting | 3 | modifies glyph outlines for maxiumum constrast | + +### Parameters + + + +
hintingLevel +one of: kNo Hinting, kSlight Hinting, kNormal Hinting, kFull Hinting
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Flags + +## Enum SkPaint::Flags + +
+enum Flags {
+kAntiAlias Flag       = 0x01,
+kDither Flag          = 0x04,
+kFakeBoldText Flag    = 0x20,
+kLinearText Flag      = 0x40,
+kSubpixelText Flag    = 0x80,
+kDevKernText Flag     = 0x100,
+kLCDRenderText Flag   = 0x200,
+kEmbeddedBitmapText Flag = 0x400,
+kAutoHinting Flag     = 0x800,
+kVerticalText Flag    = 0x1000,
+kGenA8FromLCD Flag    = 0x2000,
+
+kAllFlags = 0xFFFF,
+};
+
+ +The bit values stored in Flags. +The default value for Flags, normally zero, can be changed at compile time +with a custom definition of SkPaintDefaults Flags. +All flags can be read and written explicitly; Flags allows manipulating +multiple settings at once. + +### Constants + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Flags default to all flags clear, disabling the associated feature. + +
SkPaint::kAntiAlias_Flag 0x0001 mask for setting Anti-alias
SkPaint::kDither_Flag 0x0004mask for setting Dither
SkPaint::kFakeBoldText_Flag 0x0020mask for setting Fake Bold
SkPaint::kLinearText_Flag 0x0040mask for setting Linear Text
SkPaint::kSubpixelText_Flag 0x0080mask for setting Subpixel Text
SkPaint::kDevKernText_Flag 0x0100mask for setting Full Hinting Spacing
SkPaint::kLCDRenderText_Flag 0x0200mask for setting LCD Text
SkPaint::kEmbeddedBitmapText_Flag 0x0400mask for setting Font Embedded Bitmaps
SkPaint::kAutoHinting_Flag 0x0800mask for setting Automatic Hinting
SkPaint::kVerticalText_Flag 0x1000mask for setting Vertical Text
SkPaint::kGenA8FromLCD_Flag 0x2000not intended for public use
SkPaint::kAllFlags 0xFFFFmask of all Flags, including private flags and flags reserved for future use
+ +## Enum SkPaint::ReserveFlags + +
+enum ReserveFlags {
+kUnderlineText ReserveFlag   = 0x08,
+kStrikeThruText ReserveFlag  = 0x10,
+};
+ +### Constants + + + + + + + + +
SkPaint::kUnderlineText_ReserveFlag 0x0008mask for underline text
SkPaint::kStrikeThruText_ReserveFlag 0x0010mask for strike-thru text
+ + + + +## getFlags + +
+uint32_t getFlags() const
+
+ +Returns paint settings described by Flags. Each setting uses one +bit, and can be tested with Flags members. + +### Return Value + +zero, one, or more bits described by Flags + +### Example + +
+ +#### Example Output + +~~~~ +(SkPaint::kAntiAlias_Flag & paint.getFlags()) != 0 +~~~~ + +
+ +--- + + +## setFlags + +
+void setFlags(uint32_t flags)
+
+ +Replaces Flags with flags, the union of the Flags members. +All Flags members may be cleared, or one or more may be set. + +### Parameters + + + +
flags +union of Flags for Paint
+ +### Example + +
+ +#### Example Output + +~~~~ +paint.isAntiAlias() +paint.isDither() +~~~~ + +
+ +--- + +# Anti-alias +Anti-alias drawing approximates partial pixel coverage with transparency. +If kAntiAlias Flag is clear, pixel centers contained by the shape edge are drawn opaque. +If kAntiAlias Flag is set, pixels are drawn with Color Alpha equal to their coverage. + +The rule for aliased pixels is inconsistent across platforms. A shape edge +passing through the pixel center may, but is not required to, draw the pixel. + +Raster Engine draws aliased pixels whose centers are on or to the right of the start of an +active Path edge, and whose center is to the left of the end of the active Path edge. + +A platform may only support anti-aliased drawing. Some GPU-backed platforms use +supersampling to anti-alias all drawing, and have no mechanism to selectively +alias. + +The amount of coverage computed for anti-aliased pixels also varies across platforms. + +Anti-alias is disabled by default. +Anti-alias can be enabled by default by setting SkPaintDefaults Flags to kAntiAlias Flag +at compile time. + +### Example + +
A red line is drawn with transparency on the edges to make it look smoother. +A blue line draws only where the pixel centers are contained. +The lines are drawn into an offscreen bitmap, then drawn magified to make the +aliasing easier to see.
+ + +## isAntiAlias + +
+bool isAntiAlias() const
+
+ +If true, pixels on the active edges of Path may be drawn with partial transparency. + +Equivalent to getFlags masked with kAntiAlias Flag. + +### Return Value + +kAntiAlias Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag) +paint.isAntiAlias() == !!(paint.getFlags() & SkPaint::kAntiAlias_Flag) +~~~~ + +
+ +--- + + +## setAntiAlias + +
+void setAntiAlias(bool aa)
+
+ +Requests, but does not require, that Path edge pixels draw opaque or with +partial transparency. + +Sets kAntiAlias Flag if aa is true. +Clears kAntiAlias Flag if aa is false. + +### Parameters + + + +
aa +setting for kAntiAlias Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Dither +Dither increases fidelity by adjusting the color of adjcent pixels. +This can help to smooth color transitions and reducing banding in gradients. +Dithering lessens visible banding from kRGB 565 SkColorType +and kRGBA 8888 SkColorType gradients, +and improves rendering into a kRGB 565 SkColorType Surface. + +Dithering is always enabled for linear gradients drawing into +kRGB 565 SkColorType Surface and kRGBA 8888 SkColorType Surface. +Dither cannot be enabled for kAlpha 8 SkColorType Surface and +kRGBA F16 SkColorType Surface. + +Dither is disabled by default. +Dither can be enabled by default by setting SkPaintDefaults Flags to kDither Flag +at compile time. + +Some platform implementations may ignore dithering. Setto ignore Dither on GPU Surface. + +### Example + +
Dithering in the bottom half more closely approximates the requested color by +alternating nearby colors from pixel to pixel.
+ +### Example + +
Dithering introduces subtle adjustments to color to smooth gradients. +Drawing the gradient repeatedly with SkBlendMode::kPlus exaggerates the +dither, making it easier to see.
+ + +## isDither + +
+bool isDither() const
+
+ +If true, color error may be distributed to smooth color transition. +Equivalent to getFlags masked with kDither Flag. + +### Return Value + +kDither Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag) +paint.isDither() == !!(paint.getFlags() & SkPaint::kDither_Flag) +~~~~ + +
+ +--- + + +## setDither + +
+void setDither(bool dither)
+
+ +Requests, but does not require, to distribute color error. + +Sets kDither Flag if dither is true. +Clears kDither Flag if dither is false. + +### Parameters + + + +
dither +setting for kDither Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +### See Also + +kRGB 565 SkColorType + +--- + +### See Also + +Gradient Color RGB-565 + +# Device Text +LCD Text and Subpixel Text increase the precision of glyph position. + +When set, Flags kLCDRenderText Flag takes advantage of the organization of Color RGB stripes that +create a color, and relies +on the small size of the stripe and visual perception to make the color fringing inperceptible. +LCD Text can be enabled on devices that orient stripes horizontally or vertically, and that order +the color components as Color RGB or Color RBG. + +Flags kSubpixelText Flag uses the pixel transparency to represent a fractional offset. +As the opaqueness +of the color increases, the edge of the glyph appears to move towards the outside of the pixel. + +Either or both techniques can be enabled. +kLCDRenderText Flag and kSubpixelText Flag are clear by default. +LCD Text or Subpixel Text can be enabled by default by setting SkPaintDefaults Flags to +kLCDRenderText Flag or kSubpixelText Flag (or both) at compile time. + +### Example + +
Four commas are drawn normally and with combinations of LCD Text and Subpixel Text. +When Subpixel Text is disabled, the comma glyphs are indentical, but not evenly spaced. +When Subpixel Text is enabled, the comma glyphs are unique, but appear evenly spaced.
+ +## Linear Text + +Linear Text selects whether text is rendered as a Glyph or as a Path. +If kLinearText Flag is set, it has the same effect as setting Hinting to kNormal Hinting. +If kLinearText Flag is clear, it's the same as setting Hinting to kNo Hinting. + + +## isLinearText + +
+bool isLinearText() const
+
+ +If true, text is converted to Path before drawing and measuring. + +Equivalent to getFlags masked with kLinearText Flag. + +### Return Value + +kLinearText Flag state + +### Example + +
+ +### See Also + +setLinearText Hinting + +--- + + +## setLinearText + +
+void setLinearText(bool linearText)
+
+ +If true, text is converted to Path before drawing and measuring. +By default, kLinearText Flag is clear. + +Sets kLinearText Flag if linearText is true. +Clears kLinearText Flag if linearText is false. + +### Parameters + + + +
linearText +setting for kLinearText Flag
+ +### Example + +
+ +### See Also + +isLinearText Hinting + +--- + +## Subpixel Text + +Flags kSubpixelText Flag uses the pixel transparency to represent a fractional offset. +As the opaqueness +of the color increases, the edge of the glyph appears to move towards the outside of the pixel. + + +## isSubpixelText + +
+bool isSubpixelText() const
+
+ +If true, glyphs at different sub-pixel positions may differ on pixel edge coverage. + +Equivalent to getFlags masked with kSubpixelText Flag. + +### Return Value + +kSubpixelText Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag) +paint.isSubpixelText() == !!(paint.getFlags() & SkPaint::kSubpixelText_Flag) +~~~~ + +
+ +--- + + +## setSubpixelText + +
+void setSubpixelText(bool subpixelText)
+
+ +Requests, but does not require, that glyphs respect sub-pixel positioning. + +Sets kSubpixelText Flag if subpixelText is true. +Clears kSubpixelText Flag if subpixelText is false. + +### Parameters + + + +
subpixelText +setting for kSubpixelText Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +## LCD Text + +When set, Flags kLCDRenderText Flag takes advantage of the organization of Color RGB stripes that +create a color, and relies +on the small size of the stripe and visual perception to make the color fringing inperceptible. +LCD Text can be enabled on devices that orient stripes horizontally or vertically, and that order +the color components as Color RGB or Color RBG. + + +## isLCDRenderText + +
+bool isLCDRenderText() const
+
+ +If true, glyphs may use LCD striping to improve glyph edges. + +Returns true if Flags kLCDRenderText Flag is set. + +### Return Value + +kLCDRenderText Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag) +paint.isLCDRenderText() == !!(paint.getFlags() & SkPaint::kLCDRenderText_Flag) +~~~~ + +
+ +--- + + +## setLCDRenderText + +
+void setLCDRenderText(bool lcdText)
+
+ +Requests, but does not require, that glyphs use LCD striping for glyph edges. + +Sets kLCDRenderText Flag if lcdText is true. +Clears kLCDRenderText Flag if lcdText is false. + +### Parameters + + + +
lcdText +setting for kLCDRenderText Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Font Embedded Bitmaps +Font Embedded Bitmaps allows selecting custom-sized bitmap glyphs. +Flags kEmbeddedBitmapText Flag when set chooses an embedded bitmap glyph over an outline contained +in a font if the platform supports this option. + +FreeType selects the bitmap glyph if available when kEmbeddedBitmapText Flag is set, and selects +the outline glyph if kEmbeddedBitmapText Flag is clear. +Windows may select the bitmap glyph but is not required to do so. +OS X and iOS do not support this option. + +Font Embedded Bitmaps is disabled by default. +Font Embedded Bitmaps can be enabled by default by setting SkPaintDefaults Flags to +kEmbeddedBitmapText Flag at compile time. + +### Example + +
+!fiddle
The hintgasp TrueType font in the Skia resources/fonts directory includes an embedded
+bitmap glyph at odd font sizes. This example works on platforms that use FreeType
+as their Font Engine.
+Windows may, but is not required to, return a bitmap glyph if kEmbeddedBitmapText Flag is set.
SkBitmap bitmap;
+bitmap.allocN32Pixels(30, 15);
+bitmap.eraseColor(0);
+SkCanvas offscreen(bitmap);
+SkPaint paint;
+paint.
+ + +## isEmbeddedBitmapText + +
+bool isEmbeddedBitmapText() const
+
+ +If true, Font Engine may return glyphs from font bitmaps instead of from outlines. + +Equivalent to getFlags masked with kEmbeddedBitmapText Flag. + +### Return Value + +kEmbeddedBitmapText Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isEmbeddedBitmapText() == !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag) +paint.isEmbeddedBitmapText() == !!(paint.getFlags() & SkPaint::kEmbeddedBitmapText_Flag) +~~~~ + +
+ +--- + + +## setEmbeddedBitmapText + +
+void setEmbeddedBitmapText(bool useEmbeddedBitmapText)
+
+ +Requests, but does not require, to use bitmaps in fonts instead of outlines. + +Sets kEmbeddedBitmapText Flag if useEmbeddedBitmapText is true. +Clears kEmbeddedBitmapText Flag if useEmbeddedBitmapText is false. + +### Parameters + + + +
useEmbeddedBitmapText +setting for kEmbeddedBitmapText Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Automatic Hinting +If Hinting is set to kNormal Hinting or kFull Hinting, Automatic Hinting +instructs the Font Manager to always hint Glyphs. +Automatic Hinting has no effect if Hinting is set to kNo Hinting or +kSlight Hinting. + +Automatic Hinting only affects platforms that use FreeType as the Font Manager. + + +## isAutohinted + +
+bool isAutohinted() const
+
+ +If true, and if Hinting is set to kNormal Hinting or kFull Hinting, and if +platform uses FreeType as the Font Manager, instruct the Font Manager to always hint +Glyphs. + +Equivalent to getFlags masked with kAutoHinting Flag. + +### Return Value + +kAutoHinting Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag) +paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag) +~~~~ + +
+ +### See Also + +setAutohinted Hinting + +--- + + +## setAutohinted + +
+void setAutohinted(bool useAutohinter)
+
+ +If Hinting is set to kNormal Hinting or kFull Hinting and useAutohinter is set, +instruct the Font Manager to always hint Glyphs. +Automatic Hinting has no effect if Hinting is set to kNo Hinting or +kSlight Hinting. + +setAutohinted only affects platforms that use FreeType as the Font Manager. + +Sets kAutoHinting Flag if useAutohinter is true. +Clears kAutoHinting Flag if useAutohinter is false. + +### Parameters + + + +
useAutohinter +setting for kAutoHinting Flag
+ +### Example + +
+ +### See Also + +isAutohinted Hinting + +--- + +# Vertical Text +Text may be drawn by positioning each glyph, or by positioning the first glyph and +using Font Advance to position subsequent glyphs. By default, each successive glyph +is positioned to the right of the preceeding glyph. Vertical Text sets successive +glyphs to position below the preceeding glyph. + +Skia can translate text character codes as a series of glyphs, but does not implement +font substitution, +textual substitution, line layout, or contextual spacing like kerning pairs. Use +a text shaping engine likeHarfBuzzhttp://harfbuzz.org/to translate text runs +into glyph series. + +Vertical Text is clear if text is drawn left to right or set if drawn from top to bottom. + +Flags kVerticalText Flag if clear draws text left to right. +Flags kVerticalText Flag if set draws text top to bottom. + +Vertical Text is clear by default. +Vertical Text can be set by default by setting SkPaintDefaults Flags to +kVerticalText Flag at compile time. + +### Example + +
+ + +## isVerticalText + +
+bool isVerticalText() const
+
+ +If true, glyphs are drawn top to bottom instead of left to right. + +Equivalent to getFlags masked with kVerticalText Flag. + +### Return Value + +kVerticalText Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag) +paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag) +~~~~ + +
+ +--- + + +## setVerticalText + +
+void setVerticalText(bool verticalText)
+
+ +If true, text advance positions the next glyph below the previous glyph instead of to the +right of previous glyph. + +Sets kVerticalText Flag if vertical is true. +Clears kVerticalText Flag if vertical is false. + +### Parameters + + + +
verticalText +setting for kVerticalText Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Fake Bold +Fake Bold approximates the bold font style accompanying a normal font when a bold font face +is not available. Skia does not provide font substitution; it is up to the client to find the +bold font face using the platform's Font Manager. + +Use Text Skew X to approximate an italic font style when the italic font face +is not available. + +A FreeType-based port may define SK USE FREETYPE EMBOLDEN at compile time to direct +the font engine to create the bold glyphs. Otherwise, the extra bold is computed +by increasing the stroke width and setting the Style to kStrokeAndFill Style as needed. + +Fake Bold is disabled by default. + +### Example + +
+ + +## isFakeBoldText + +
+bool isFakeBoldText() const
+
+ +If true, approximate bold by increasing the stroke width when creating glyph bitmaps +from outlines. + +Equivalent to getFlags masked with kFakeBoldText Flag. + +### Return Value + +kFakeBoldText Flag state + +### Example + +
+ +#### Example Output + +~~~~ +paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag) +paint.isFakeBoldText() == !!(paint.getFlags() & SkPaint::kFakeBoldText_Flag) +~~~~ + +
+ +--- + + +## setFakeBoldText + +
+void setFakeBoldText(bool fakeBoldText)
+
+ +Use increased stroke width when creating glyph bitmaps to approximate bolding. + +Sets kFakeBoldText Flag if fakeBoldText is true. +Clears kFakeBoldText Flag if fakeBoldText is false. + +### Parameters + + + +
fakeBoldText +setting for kFakeBoldText Flag
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Full Hinting Spacing +Full Hinting Spacing adjusts the character spacing by the difference of the +hinted and unhinted left and right side bearings, +if Hinting is set to kFull Hinting. Full Hinting Spacing only +applies to platforms that use FreeType as their Font Engine. + +Full Hinting Spacing is not related to text kerning, where the space between +a specific pair of characters is adjusted using data in the font's kerning tables. + + +## isDevKernText + +
+bool isDevKernText() const
+
+ +Returns if character spacing may be adjusted by the hinting difference. + +Equivalent to getFlags masked with kDevKernText Flag. + +### Return Value + +kDevKernText Flag state + +### Example + +
+ +--- + + +## setDevKernText + +
+void setDevKernText(bool devKernText)
+
+ +Requests, but does not require, to use hinting to adjust glyph spacing. + +Sets kDevKernText Flag if devKernText is true. +Clears kDevKernText Flag if devKernText is false. + +### Parameters + + + +
devKernText +setting for devKernText
+ +### Example + +
+ +#### Example Output + +~~~~ +paint1 == paint2 +~~~~ + +
+ +--- + +# Filter Quality Methods +Filter Quality trades speed for image filtering when the image is scaled. +A lower Filter Quality draws faster, but has less fidelity. +A higher Filter Quality draws slower, but looks better. +If the image is unscaled, the Filter Quality choice will not result in a noticable +difference. + +Filter Quality is used in Paint passed as a parameter to + + + + + + +
SkCanvas::drawBitmap
SkCanvas::drawBitmapRect
SkCanvas::drawImage
SkCanvas::drawImageRect
+ +and when Paint has a Shader specialization that uses Image or Bitmap. + +Filter Quality is kNone SkFilterQuality by default. + +### Example + +
+ + +## getFilterQuality + +
+SkFilterQuality getFilterQuality() const
+
+ +Returns Filter Quality, the image filtering level. A lower setting +draws faster; a higher setting looks better when the image is scaled. + +### Return Value + +one of: kNone SkFilterQuality, kLow SkFilterQuality, +kMedium SkFilterQuality, kHigh SkFilterQuality + +### Example + +
+ +#### Example Output + +~~~~ +kNone_SkFilterQuality == paint.getFilterQuality() +~~~~ + +
+ +--- + + +## setFilterQuality + +
+void setFilterQuality(SkFilterQuality quality)
+
+ +Sets Filter Quality, the image filtering level. A lower setting +draws faster; a higher setting looks better when the image is scaled. +setFilterQuality does not check to see if quality is valid. + +### Parameters + + + +
quality +one of: kNone SkFilterQuality, kLow SkFilterQuality, +kMedium SkFilterQuality, kHigh SkFilterQuality
+ +### Example + +
+ +#### Example Output + +~~~~ +kHigh_SkFilterQuality == paint.getFilterQuality() +~~~~ + +
+ +### See Also + +SkFilterQuality Image Scaling + +--- + +# Color Methods +Color specifies the Color RGB Red, Color RGB Blue, Color RGB Green, and Color Alpha values used to draw a filled +or stroked shape in a +32-bit value. Each component occupies 8-bits, ranging from zero: no contribution; +to 255: full intensity. All values in any combination are valid. + +Color is not premultiplied; +Color Alpha sets the transparency independent of Color RGB: Color RGB Red, Color RGB Blue, and Color RGB Green. + +The bit positions of Color Alpha and Color RGB are independent of the bit positions +on the output device, which may have more or fewer bits, and may have a different arrangement. + +| bit positions | Color Alpha | Color RGB Red | Color RGB Blue | Color RGB Green | +| --- | --- | --- | --- | --- | +| | 31 - 24 | 23 - 16 | 15 - 8 | 7 - 0 | + +### Example + +
+ + +## getColor + +
+SkColor getColor() const
+
+ +Retrieves Color Alpha and Color RGB, unpremultiplied, packed into 32 bits. +Use helpers SkColorGetA, SkColorGetR, SkColorGetG, and SkColorGetB to extract +a color component. + +### Return Value + +Unpremultiplied Color ARGB + +### Example + +
+ +#### Example Output + +~~~~ +Yellow is 100% red, 100% green, and 0% blue. +~~~~ + +
+ +### See Also + +SkColor + +--- + + +## setColor + +
+void setColor(SkColor color)
+
+ +Sets Color Alpha and Color RGB used when stroking and filling. The color is a 32-bit value, +unpremutiplied, packing 8-bit components for Color Alpha, Color RGB Red, Color RGB Blue, and Color RGB Green. + +### Parameters + + + +
color +Unpremultiplied Color ARGB
+ +### Example + +
+ +#### Example Output + +~~~~ +green1 == green2 +~~~~ + +
+ +### See Also + +SkColor setARGB SkColorSetARGB + +--- + +## Alpha Methods + +Color Alpha sets the transparency independent of Color RGB: Color RGB Red, Color RGB Blue, and Color RGB Green. + + +## getAlpha + +
+uint8_t getAlpha() const
+
+ +Retrieves Color Alpha from the Color used when stroking and filling. + +### Return Value + +Color Alpha ranging from zero, fully transparent, to 255, fully opaque + +### Example + +
+ +#### Example Output + +~~~~ +255 == paint.getAlpha() +~~~~ + +
+ +--- + + +## setAlpha + +
+void setAlpha(U8CPU a)
+
+ +Replaces Color Alpha, leaving Color RGB +unchanged. An out of range value triggers an assert in the debug +build. a is a value from zero to 255. +a set to zero makes Color fully transparent; a set to 255 makes Color +fully opaque. + +### Parameters + + + +
a +Color Alpha component of Color
+ +### Example + +
+ +#### Example Output + +~~~~ +0x44112233 == paint.getColor() +~~~~ + +
+ +--- + + +## setARGB + +
+void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b)
+
+ +Sets Color used when drawing solid fills. The color components range from 0 to 255. +The color is unpremultiplied; +Color Alpha sets the transparency independent of Color RGB. + +### Parameters + + + + + + +
a +amount of Color Alpha, from fully transparent (0) to fully opaque (255)
r +amount of Color RGB Red, from no red (0) to full red (255)
g +amount of Color RGB Green, from no green (0) to full green (255)
b +amount of Color RGB Blue, from no blue (0) to full blue (255)
+ +### Example + +
+ +#### Example Output + +~~~~ +transRed1 == transRed2 +~~~~ + +
+ +### See Also + +setColor SkColorSetARGB + +--- + +# Style +Style specifies if the geometry is filled, stroked, or both filled and stroked. +Some shapes ignore Style and are always drawn filled or stroked. + +Set Style to kFill Style to fill the shape. +The fill covers the area inside the geometry for most shapes. + +Set Style to kStroke Style to stroke the shape. + +## Fill + +### See Also + +Path Fill Type + +## Stroke + +The stroke covers the area described by following the shape's edge with a pen or brush of +Stroke Width. The area covered where the shape starts and stops is described by Stroke Cap. +The area covered where the shape turns a corner is described by Stroke Join. +The stroke is centered on the shape; it extends equally on either side of the shape's edge. + +As Stroke Width gets smaller, the drawn path frame is thinner. Stroke Width less than one +may have gaps, and if kAntiAlias Flag is set, Color Alpha will increase to visually decrease coverage. + +## Hairline + +Stroke Width of zero has a special meaning and switches drawing to use Hairline. +Hairline draws the thinnest continuous frame. If kAntiAlias Flag is clear, adjacent pixels +flow horizontally, vertically,or diagonally. + +Path drawing with Hairline may hit the same pixel more than once. For instance, Path containing +two lines in one Path Contour will draw the corner point once, but may both lines may draw the adjacent +pixel. If kAntiAlias Flag is set, transparency is applied twice, resulting in a darker pixel. Some +GPU-backed implementations apply transparency at a later drawing stage, avoiding double hit pixels +while stroking. + +## Enum SkPaint::Style + +
+enum Style {
+kFill Style,
+kStroke Style,
+kStrokeAndFill Style,
+};
+ +Set Style to fill, stroke, or both fill and stroke geometry. +The stroke and fill +share all paint attributes; for instance, they are drawn with the same color. + +Use kStrokeAndFill Style to avoid hitting the same pixels twice with a stroke draw and +a fill draw. + +### Constants + + + + + + + + + + + + +
SkPaint::kFill_Style 0Set to fill geometry. +Applies to Rect, Region, Round Rect, Circle, Oval, Path, and Text. +Bitmap, Image, Patch, Region, Sprite, and Vertices are painted as if +kFill Style is set, and ignore the set Style. +The Path Fill Type specifies additional rules to fill the area outside the path edge, +and to create an unfilled hole inside the shape. +Style is set to kFill Style by default.
SkPaint::kStroke_Style 1Set to stroke geometry. +Applies to Rect, Region, Round Rect, Arc, Circle, Oval, +Path, and Text. +Arc, Line, Point, and Point Array are always drawn as if kStroke Style is set, +and ignore the set Style. +The stroke construction is unaffected by the Path Fill Type.
SkPaint::kStrokeAndFill_Style 2Set to stroke and fill geometry. +Applies to Rect, Region, Round Rect, Circle, Oval, Path, and Text. +Path is treated as if it is set to SkPath::kWinding FillType, +and the set Path Fill Type is ignored.
+ +## Enum SkPaint::_anonymous + +
+enum {
+kStyleCount = kStrokeAndFill Style + 1
+};
+ +### Constants + + + + + + +
SkPaint::kStyleCount 3The number of different Style values defined. +May be used to verify that Style is a legal value.
+ + +## getStyle + +
+Style getStyle() const
+
+ +Whether the geometry is filled, stroked, or filled and stroked. + +### Return Value + +one of:kFill Style, kStroke Style, kStrokeAndFill Style + +### Example + +
+ +#### Example Output + +~~~~ +SkPaint::kFill_Style == paint.getStyle() +~~~~ + +
+ +### See Also + +Style setStyle + +--- + + +## setStyle + +
+void setStyle(Style style)
+
+ +Sets whether the geometry is filled, stroked, or filled and stroked. +Has no effect if style is not a legal Style value. + +### Parameters + + + +
style +one of: kFill Style, kStroke Style, kStrokeAndFill Style
+ +### Example + +
+ +### See Also + +Style getStyle + +--- + +### See Also + +Path Fill Type Path Effect Style Fill Style Stroke + +# Stroke Width +Stroke Width sets the width for stroking. The width is the thickness +of the stroke perpendicular to the path's direction when the paint's style is +set to kStroke Style or kStrokeAndFill Style. + +When width is greater than zero, the stroke encompasses as many pixels partially +or fully as needed. When the width equals zero, the paint enables hairlines; +the stroke is always one pixel wide. + +The stroke's dimensions are scaled by the canvas matrix, but Hairline stroke +remains one pixel wide regardless of scaling. + +The default width for the paint is zero. + +### Example + +
raster gpu
The pixels hit to represent thin lines vary with the angle of the +line and the platform's implementation.
+ + +## getStrokeWidth + +
+SkScalar getStrokeWidth() const
+
+ +Returns the thickness of the pen used by Paint to +outline the shape. + +### Return Value + +zero for Hairline, greater than zero for pen thickness + +### Example + +
+ +#### Example Output + +~~~~ +0 == paint.getStrokeWidth() +~~~~ + +
+ +--- + + +## setStrokeWidth + +
+void setStrokeWidth(SkScalar width)
+
+ +Sets the thickness of the pen used by the paint to +outline the shape. +Has no effect if width is less than zero. + +### Parameters + + + +
width +zero thickness for Hairline; greater than zero for pen thickness
+ +### Example + +
+ +#### Example Output + +~~~~ +5 == paint.getStrokeWidth() +~~~~ + +
+ +--- + +# Miter Limit +Miter Limit specifies the maximum miter length, +relative to the stroke width. + +Miter Limit is used when the Stroke Join +is set to kMiter Join, and the Style is either kStroke Style +or kStrokeAndFill Style. + +If the miter at a corner exceeds this limit, kMiter Join +is replaced with kBevel Join. + +Miter Limit can be computed from the corner angle: + +miter limit = 1 / sin ( angle / 2 )Miter Limit default value is 4. +The default may be changed at compile time by setting SkPaintDefaults MiterLimit +in SkUserConfig.h or as a define supplied by the build environment. + +Here are some miter limits and the angles that triggers them. + +| miter limit | angle in degrees | +| --- | --- | +| 10 | 11.48 | +| 9 | 12.76 | +| 8 | 14.36 | +| 7 | 16.43 | +| 6 | 19.19 | +| 5 | 23.07 | +| 4 | 28.96 | +| 3 | 38.94 | +| 2 | 60 | +| 1 | 180 | + +### Example + +
This example draws a stroked corner and the miter length beneath. +When the miter limit is decreased slightly, the miter join is replaced +by a bevel join.
+ + +## getStrokeMiter + +
+SkScalar getStrokeMiter() const
+
+ +The limit at which a sharp corner is drawn beveled. + +### Return Value + +zero and greater Miter Limit + +### Example + +
+ +#### Example Output + +~~~~ +default miter limit == 4 +~~~~ + +
+ +### See Also + +Miter Limit setStrokeMiter Join + +--- + + +## setStrokeMiter + +
+void setStrokeMiter(SkScalar miter)
+
+ +The limit at which a sharp corner is drawn beveled. +Valid values are zero and greater. +Has no effect if miter is less than zero. + +### Parameters + + + +
miter +zero and greater Miter Limit
+ +### Example + +
+ +#### Example Output + +~~~~ +default miter limit == 8 +~~~~ + +
+ +### See Also + +Miter Limit getStrokeMiter Join + +--- + +# Stroke Cap + +## Enum SkPaint::Cap + +
+enum Cap {
+kButt Cap,
+kRound Cap,
+kSquare Cap,
+
+kLast Cap = kSquare Cap,
+kDefault Cap = kButt Cap
+};
+static constexpr int kCapCount = kLast Cap + 1;
+ +Stroke Cap draws at the beginning and end of an open Path Contour. + +### Constants + + + + + + + + + + + + + + + + + + + + + +Stroke describes the area covered by a pen of Stroke Width as it +follows the Path Contour, moving parallel to the contours's direction. + +If the Path Contour is not terminated by SkPath::kClose Verb, the contour has a +visible beginning and end. + +Path Contour may start and end at the same point; defining Zero Length Contour. + +kButt Cap and Zero Length Contour is not drawn. +kRound Cap and Zero Length Contour draws a circle of diameter Stroke Width +at the contour point. +kSquare Cap and Zero Length Contour draws an upright square with a side of +Stroke Width at the contour point. + +Stroke Cap is kButt Cap by default. + +
SkPaint::kButt_Cap 0Does not extend the stroke past the beginning or the end.
SkPaint::kRound_Cap 1Adds a circle with a diameter equal to Stroke Width at the beginning +and end.
SkPaint::kSquare_Cap 2Adds a square with sides equal to Stroke Width at the beginning +and end. The square sides are parallel to the initial and final direction +of the stroke.
SkPaint::kLast_Cap 2Equivalent to the largest value for Stroke Cap.
SkPaint::kDefault_Cap 0Equivalent to kButt Cap. +Stroke Cap is set to kButt Cap by default.
SkPaint::kCapCount 3The number of different Stroke Cap values defined. +May be used to verify that Stroke Cap is a legal value.
+ +### Example + +
+ + +## getStrokeCap + +
+Cap getStrokeCap() const
+
+ +The geometry drawn at the beginning and end of strokes. + +### Return Value + +one of: kButt Cap, kRound Cap, kSquare Cap + +### Example + +
+ +#### Example Output + +~~~~ +kButt_Cap == default stroke cap +~~~~ + +
+ +### See Also + +Stroke Cap setStrokeCap + +--- + + +## setStrokeCap + +
+void setStrokeCap(Cap cap)
+
+ +The geometry drawn at the beginning and end of strokes. + +### Parameters + + + +
cap +one of: kButt Cap, kRound Cap, kSquare Cap; +has no effect if cap is not valid
+ +### Example + +
+ +#### Example Output + +~~~~ +kRound_Cap == paint.getStrokeCap() +~~~~ + +
+ +### See Also + +Stroke Cap getStrokeCap + +--- + +# Stroke Join +Stroke Join draws at the sharp corners of an open or closed Path Contour. + +Stroke describes the area covered by a pen of Stroke Width as it +follows the Path Contour, moving parallel to the contours's direction. + +If the contour direction changes abruptly, because the tangent direction leading +to the end of a curve within the contour does not match the tangent direction of +the following curve, the pair of curves meet at Stroke Join. + +### Example + +
+ +## Enum SkPaint::Join + +
+enum Join {
+kMiter Join,
+kRound Join,
+kBevel Join,
+
+kLast Join = kBevel Join,
+kDefault Join = kMiter Join
+};
+static constexpr int kJoinCount = kLast Join + 1;
+ +Join specifies how corners are drawn when a shape is stroked. The paint's Join setting +affects the four corners of a stroked rectangle, and the connected segments in a +stroked path. + +Choose miter join to draw sharp corners. Choose round join to draw a circle with a +radius equal to the stroke width on top of the corner. Choose bevel join to minimally +connect the thick strokes. + +The fill path constructed to describe the stroked path respects the join setting but may +not contain the actual join. For instance, a fill path constructed with round joins does +not necessarily include circles at each connected segment. + +### Constants + + + + + + + + + + + + + + + + + + + + +
SkPaint::kMiter_Join 0Extends the outside corner to the extent allowed by Miter Limit. +If the extension exceeds Miter Limit, kBevel Join is used instead.
SkPaint::kRound_Join 1Adds a circle with a diameter of Stroke Width at the sharp corner.
SkPaint::kBevel_Join 2Connects the outside edges of the sharp corner.
SkPaint::kLast_Join 2Equivalent to the largest value for Stroke Join.
SkPaint::kDefault_Join 1Equivalent to kMiter Join. +Stroke Join is set to kMiter Join by default.
SkPaint::kJoinCount 3The number of different Stroke Join values defined. +May be used to verify that Stroke Join is a legal value.
+ +### Example + +
+ +### See Also + +setStrokeJoin getStrokeJoin setStrokeMiter getStrokeMiter + + + + +## getStrokeJoin + +
+Join getStrokeJoin() const
+
+ +The geometry drawn at the corners of strokes. + +### Return Value + +one of: kMiter Join, kRound Join, kBevel Join + +### Example + +
+ +#### Example Output + +~~~~ +kMiter_Join == default stroke join +~~~~ + +
+ +### See Also + +Stroke Join setStrokeJoin + +--- + + +## setStrokeJoin + +
+void setStrokeJoin(Join join)
+
+ +The geometry drawn at the corners of strokes. + +### Parameters + + + +
join +one of: kMiter Join, kRound Join, kBevel Join; +otherwise, setStrokeJoin has no effect
+ +### Example + +
+ +#### Example Output + +~~~~ +kMiter_Join == paint.getStrokeJoin() +~~~~ + +
+ +### See Also + +Stroke Join getStrokeJoin + +--- + +### See Also + +Miter Limit + +# Fill Path +Fill Path creates a Path by applying the Path Effect, followed by the Style Stroke. + +If Paint contains Path Effect, Path Effect operates on the source Path; the result +replaces the destination Path. Otherwise, the source Path is replaces the +destination Path. + +Fill Path can request the Path Effect to restrict to a culling rectangle, but +the Path Effect is not required to do so. + +If Style is kStroke Style or kStrokeAndFill Style, +and Stroke Width is greater than zero, the Stroke Width, Stroke Cap, Stroke Join, +and Miter Limit operate on the destination Path, replacing it. + +Fill Path can specify the precision used by Stroke Width to approximate the stroke geometry. + +If the Style is kStroke Style and the Stroke Width is zero, getFillPath +returns false since Hairline has no filled equivalent. + + +## getFillPath + +
+bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect,
+                 SkScalar resScale = 1) const
+
+ +The filled equivalent of the stroked path. + +### Parameters + + + + + + +
src +Path read to create a filled version
dst +resulting Path; may be the same as src, but may not be nullptr
cullRect +optional limit passed to Path Effect
resScale +if > 1, increase precision, else if (0 < res < 1) reduce precision +to favor speed and size
+ +### Return Value + +true if the path represents Style Fill, or false if it represents Hairline + +### Example + +
A very small quad stroke is turned into a filled path with increasing levels of precision. +At the lowest precision, the quad stroke is approximated by a rectangle. +At the highest precision, the filled path has high fidelity compared to the original stroke.
+ +--- + +
+bool getFillPath(const SkPath& src, SkPath* dst) const
+
+ +The filled equivalent of the stroked path. + +Replaces dst with the src path modified by Path Effect and Style Stroke. +Path Effect, if any, is not culled. Stroke Width is created with default precision. + +### Parameters + + + + +
src +Path read to create a filled version
dst +resulting Path dst may be the same as src, but may not be nullptr
+ +### Return Value + +true if the path represents Style Fill, or false if it represents Hairline + +### Example + +
+ +--- + +### See Also + +Style Stroke Stroke Width Path Effect + +# Shader Methods +Shader defines the colors used when drawing a shape. +Shader may be an image, a gradient, or a computed fill. +If Paint has no Shader, then Color fills the shape. + +Shader is modulated by Color Alpha component of Color. +If Shader object defines only Color Alpha, then Color modulated by Color Alpha describes +the fill. + +The drawn transparency can be modified without altering Shader, by changing Color Alpha. + +### Example + +
+ +If Shader generates only Color Alpha then all components of Color modulate the output. + +### Example + +
+ + +## getShader + +
+SkShader* getShader() const
+
+ +Optional colors used when filling a path, such as a gradient. + +Does not alter Shader Reference Count. + +### Return Value + +Shader if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == shader +nullptr != shader +~~~~ + +
+ +--- + + +## refShader + +
+sk_sp refShader() const
+
+ +Optional colors used when filling a path, such as a gradient. + +Increases Shader Reference Count by one. + +### Return Value + +Shader if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +shader unique: true +shader unique: false +~~~~ + +
+ +--- + + +## setShader + +
+void setShader(sk_sp shader)
+
+ +Optional colors used when filling a path, such as a gradient. + +Sets Shader to shader, decrementing Reference Count of the previous Shader. +Does not alter shader Reference Count. + +### Parameters + + + +
shader +how geometry is filled with color; if nullptr, Color is used instead
+ +### Example + +
+ +--- + +# Color Filter Methods +Color Filter alters the color used when drawing a shape. +Color Filter may apply Blend Mode, transform the color through a matrix, or composite multiple filters. +If Paint has no Color Filter, the color is unaltered. + +The drawn transparency can be modified without altering Color Filter, by changing Color Alpha. + +### Example + +
+ + +## getColorFilter + +
+SkColorFilter* getColorFilter() const
+
+ +Returns Color Filter if set, or nullptr. +Does not alter Color Filter Reference Count. + +### Return Value + +Color Filter if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == color filter +nullptr != color filter +~~~~ + +
+ +--- + + +## refColorFilter + +
+sk_sp refColorFilter() const
+
+ +Returns Color Filter if set, or nullptr. +Increases Color Filter Reference Count by one. + +### Return Value + +Color Filter if set, or nullptr + +### Example + +
+ +#### Example Output + +~~~~ +color filter unique: true +color filter unique: false +~~~~ + +
+ +--- + + +## setColorFilter + +
+void setColorFilter(sk_sp colorFilter)
+
+ +Sets Color Filter to filter, decrementing Reference Count of the previous Color Filter. +Pass nullptr to clear Color Filter. +Does not alter filter Reference Count. + +### Parameters + + + +
colorFilter +Color Filter to apply to subsequent draw
+ +### Example + +
+ +--- + +# Blend Mode Methods +Blend Mode describes how Color combines with the destination color. +The default setting, SkBlendMode::kSrcOver, draws the source color +over the destination color. + +### Example + +
+ +### See Also + +Blend Mode + + +## getBlendMode + +
+SkBlendMode getBlendMode() const
+
+ +Returns Blend Mode. +By default, getBlendMode returns SkBlendMode::kSrcOver. + +### Return Value + +mode used to combine source color with destination color + +### Example + +
+ +#### Example Output + +~~~~ +kSrcOver == getBlendMode +kSrcOver != getBlendMode +~~~~ + +
+ +--- + + +## isSrcOver + +
+bool isSrcOver() const
+
+ +Returns true if Blend Mode is SkBlendMode::kSrcOver, the default. + +### Return Value + +true if Blend Mode is SkBlendMode::kSrcOver + +### Example + +
+ +#### Example Output + +~~~~ +isSrcOver == true +isSrcOver != true +~~~~ + +
+ +--- + + +## setBlendMode + +
+void setBlendMode(SkBlendMode mode)
+
+ +Sets Blend Mode to mode. +Does not check for valid input. + +### Parameters + + + +
mode +SkBlendMode used to combine source color and destination
+ +### Example + +
+ +#### Example Output + +~~~~ +isSrcOver == true +isSrcOver != true +~~~~ + +
+ +--- + +# Path Effect Methods +Path Effect modifies the path geometry before drawing it. +Path Effect may implement dashing, custom fill effects and custom stroke effects. +If Paint has no Path Effect, the path geometry is unaltered when filled or stroked. + +### Example + +
+ +### See Also + +Path Effect + + +## getPathEffect + +
+SkPathEffect* getPathEffect() const
+
+ +Returns Path Effect if set, or nullptr. +Does not alter Path Effect Reference Count. + +### Return Value + +Path Effect if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == path effect +nullptr != path effect +~~~~ + +
+ +--- + + +## refPathEffect + +
+sk_sp refPathEffect() const
+
+ +Returns Path Effect if set, or nullptr. +Increases Path Effect Reference Count by one. + +### Return Value + +Path Effect if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +path effect unique: true +path effect unique: false +~~~~ + +
+ +--- + + +## setPathEffect + +
+void setPathEffect(sk_sp pathEffect)
+
+ +Sets Path Effect to pathEffect, +decrementing Reference Count of the previous Path Effect. +Pass nullptr to leave the path geometry unaltered. +Does not alter pathEffect Reference Count. + +### Parameters + + + +
pathEffect +replace Path with a modification when drawn
+ +### Example + +
+ +--- + +# Mask Filter Methods +Mask Filter uses Color Alpha of the shape drawn to create Mask Alpha. +Mask Filter operates at a lower level than Rasterizer; Mask Filter takes a Mask, +and returns a Mask. +Mask Filter may change the geometry and transparency of the shape, such as creating a blur effect. +Set Mask Filter to nullptr to prevent Mask Filter from modifying the draw. + +### Example + +
+ + +## getMaskFilter + +
+SkMaskFilter* getMaskFilter() const
+
+ +Returns Mask Filter if set, or nullptr. +Does not alter Mask Filter Reference Count. + +### Return Value + +Mask Filter if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == mask filter +nullptr != mask filter +~~~~ + +
+ +--- + + +## refMaskFilter + +
+sk_sp refMaskFilter() const
+
+ +Returns Mask Filter if set, or nullptr. +Increases Mask Filter Reference Count by one. + +### Return Value + +Mask Filter if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +mask filter unique: true +mask filter unique: false +~~~~ + +
+ +--- + + +## setMaskFilter + +
+void setMaskFilter(sk_sp maskFilter)
+
+ +Sets Mask Filter to maskFilter, +decrementing Reference Count of the previous Mask Filter. +Pass nullptr to clear Mask Filter and leave Mask Filter effect on Mask Alpha unaltered. +Does not affect Rasterizer. +Does not alter maskFilter Reference Count. + +### Parameters + + + +
maskFilter +modifies clipping mask generated from drawn geometry
+ +### Example + +
+ +--- + +# Typeface Methods +Typeface identifies the font used when drawing and measuring text. +Typeface may be specified by name, from a file, or from a data stream. +The default Typeface defers to the platform-specific default font +implementation. + +### Example + +
+ + +## getTypeface + +
+SkTypeface* getTypeface() const
+
+ +Returns Typeface if set, or nullptr. +Does not alter Typeface Reference Count. + +### Return Value + +Typeface if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == typeface +nullptr != typeface +~~~~ + +
+ +--- + + +## refTypeface + +
+sk_sp refTypeface() const
+
+ +Increases Typeface Reference Count by one. + +### Return Value + +Typeface if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +typeface1 != typeface2 +typeface1 == typeface2 +~~~~ + +
+ +--- + + +## setTypeface + +
+void setTypeface(sk_sp typeface)
+
+ +Sets Typeface to typeface, +decrementing Reference Count of the previous Typeface. +Pass nullptr to clear Typeface and use the default typeface. +Does not alter typeface Reference Count. + +### Parameters + + + +
typeface +font and style used to draw text
+ +### Example + +
+ +--- + +# Rasterizer Methods +Rasterizer controls how shapes are converted to Mask Alpha. +Rasterizer operates at a higher level than Mask Filter; Rasterizer takes a Path, +and returns a Mask. +Rasterizer may change the geometry and transparency of the shape, such as +creating a shadow effect. Rasterizer forms the base of Rasterizer Layer, which +creates effects like embossing and outlining. +Rasterizer applies to Rect, Region, Round Rect, Arc, Circle, Oval, +Path, and Text. + +### Example + +
+ + +## getRasterizer + +
+SkRasterizer* getRasterizer() const
+
+ +Returns Rasterizer if set, or nullptr. +Does not alter Rasterizer Reference Count. + +### Return Value + +Rasterizer if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == rasterizer +nullptr != rasterizer +~~~~ + +
+ +--- + + +## refRasterizer + +
+sk_sp refRasterizer() const
+
+ +Returns Rasterizer if set, or nullptr. +Increases Rasterizer Reference Count by one. + +### Return Value + +Rasterizer if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +rasterizer unique: true +rasterizer unique: false +~~~~ + +
+ +--- + + +## setRasterizer + +
+void setRasterizer(sk_sp rasterizer)
+
+ +Sets Rasterizer to rasterizer, +decrementing Reference Count of the previous Rasterizer. +Pass nullptr to clear Rasterizer and leave Rasterizer effect on Mask Alpha unaltered. +Does not affect Mask Filter. +Does not alter rasterizer Reference Count. + +### Parameters + + + +
rasterizer +how geometry is converted to Mask Alpha
+ +### Example + +
+ +--- + +# Image Filter Methods +Image Filter operates on the pixel representation of the shape, as modified by Paint +with Blend Mode set to SkBlendMode::kSrcOver. Image Filter creates a new bitmap, +which is drawn to the device using the set Blend Mode. +Image Filter is higher level than Mask Filter; for instance, an Image Filter +can operate on all channels of Color, while Mask Filter generates Color Alpha only. +Image Filter operates independently of and can be used in combination with +Mask Filter and Rasterizer. + +### Example + +
+ + +## getImageFilter + +
+SkImageFilter* getImageFilter() const
+
+ +Returns Image Filter if set, or nullptr. +Does not alter Image Filter Reference Count. + +### Return Value + +Image Filter if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == image filter +nullptr != image filter +~~~~ + +
+ +--- + + +## refImageFilter + +
+sk_sp refImageFilter() const
+
+ +Returns Image Filter if set, or nullptr. +Increases Image Filter Reference Count by one. + +### Return Value + +Image Filter if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +image filter unique: true +image filter unique: false +~~~~ + +
+ +--- + + +## setImageFilter + +
+void setImageFilter(sk_sp imageFilter)
+
+ +Sets Image Filter to imageFilter, +decrementing Reference Count of the previous Image Filter. +Pass nullptr to clear Image Filter, and remove Image Filter effect +on drawing. +Does not affect Rasterizer or Mask Filter. +Does not alter imageFilter Reference Count. + +### Parameters + + + +
imageFilter +how Image is sampled when transformed
+ +### Example + +
+ +--- + +# Draw Looper Methods +Draw Looper sets a modifier that communicates state from one Draw Layer +to another to construct the draw. +Draw Looper draws one or more times, modifying the canvas and paint each time. +Draw Looper may be used to draw multiple colors or create a colored shadow. +Set Draw Looper to nullptr to prevent Draw Looper from modifying the draw. + +### Example + +
+ + +## getDrawLooper + +
+SkDrawLooper* getDrawLooper() const
+
+ +Returns Draw Looper if set, or nullptr. +Does not alter Draw Looper Reference Count. + +### Return Value + +Draw Looper if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +nullptr == draw looper +nullptr != draw looper +~~~~ + +
+ +--- + + +## refDrawLooper + +
+sk_sp refDrawLooper() const
+
+ +Returns Draw Looper if set, or nullptr. +Increases Draw Looper Reference Count by one. + +### Return Value + +Draw Looper if previously set, nullptr otherwise + +### Example + +
+ +#### Example Output + +~~~~ +draw looper unique: true +draw looper unique: false +~~~~ + +
+ +--- + + +## getLooper + +
+SkDrawLooper* getLooper() const
+
+ +Deprecated. + +(see bug.skia.org/6259) + +### Return Value + +Draw Looper if previously set, nullptr otherwise + +--- + + +## setDrawLooper + +
+void setDrawLooper(sk_sp drawLooper)
+
+ +Sets Draw Looper to drawLooper, +decrementing Reference Count of the previous drawLooper. +Pass nullptr to clear Draw Looper and leave Draw Looper effect on drawing unaltered. +setDrawLooper does not alter drawLooper Reference Count. + +### Parameters + + + +
drawLooper +Iterates through drawing one or more time, altering Paint
+ +### Example + +
+ +--- + + +## setLooper + +
+void setLooper(sk_sp drawLooper)
+
+ +Deprecated. + +(see bug.skia.org/6259) + +### Parameters + + + + +--- + +
drawLooper +sets Draw Looper to drawLooper
+ +# Text Align + +## Enum SkPaint::Align + +
+enum Align {
+kLeft Align,
+kCenter Align,
+kRight Align,
+};
+ +Align adjusts the text relative to the text position. +Align affects glyphs drawn with: SkCanvas::drawText, SkCanvas::drawPosText, +SkCanvas::drawPosTextH, SkCanvas::drawTextOnPath, +SkCanvas::drawTextOnPathHV, SkCanvas::drawTextRSXform, SkCanvas::drawTextBlob, +and SkCanvas::drawString; +as well as calls that place text glyphs like getTextWidths and getTextPath. + +The text position is set by the font for both horizontal and vertical text. +Typically, for horizontal text, the position is to the left side of the glyph on the +base line; and for vertical text, the position is the horizontal center of the glyph +at the caps height. + +Align adjusts the glyph position to center it or move it to abut the position +using the metrics returned by the font. + +Align defaults to kLeft Align. + +### Constants + + + + + + + + + + + + +
SkPaint::kLeft_Align 0Leaves the glyph at the position computed by the font offset by the text position.
SkPaint::kCenter_Align 1Moves the glyph half its width if Flags has kVerticalText Flag clear, and +half its height if Flags has kVerticalText Flag set.
SkPaint::kRight_Align 2Moves the glyph by its width if Flags has kVerticalText Flag clear, +and by its height if Flags has kVerticalText Flag set.
+ +## Enum SkPaint::_anonymous_2 + +
+enum {
+kAlignCount = 3
+};
+ +### Constants + + + + + + +
SkPaint::kAlignCount 3The number of different Text Align values defined.
+ +### Example + +
Each position separately moves the glyph in drawPosText.
+ +### Example + +
Vertical Text treats kLeft Align as top align, and kRight Align as bottom align.
+ + +## getTextAlign + +
+Align getTextAlign() const
+
+ +Returns Text Align. +Returns kLeft Align if Text Align has not been set. + +### Return Value + +text placement relative to position + +### Example + +
+ +#### Example Output + +~~~~ +kLeft_Align == default +~~~~ + +
+ +--- + + +## setTextAlign + +
+void    setTextAlign(Align align)
+
+ +Sets Text Align to align. +Has no effect if align is an invalid value. + +### Parameters + + + +
align +text placement relative to position
+ +### Example + +
Text is left-aligned by default, and then set to center. Setting the +alignment out of range has no effect.
+ +--- + +# Text Size +Text Size adjusts the overall text size in points. +Text Size can be set to any positive value or zero. +Text Size defaults to 12. +Set SkPaintDefaults TextSize at compile time to change the default setting. + +### Example + +
+ + +## getTextSize + +
+SkScalar getTextSize() const
+
+ +Returns Text Size in points. + +### Return Value + +typographic height of text + +### Example + +
+ +--- + + +## setTextSize + +
+void setTextSize(SkScalar textSize)
+
+ +Sets Text Size in points. +Has no effect if textSize is not greater than or equal to zero. + +### Parameters + + + +
textSize +typographic height of text
+ +### Example + +
+ +--- + +# Text Scale X +Text Scale X adjusts the text horizontal scale. +Text scaling approximates condensed and expanded type faces when the actual face +is not available. +Text Scale X can be set to any value. +Text Scale X defaults to 1. + +### Example + +
+ + +## getTextScaleX + +
+SkScalar getTextScaleX() const
+
+ +Returns Text Scale X. +Default value is 1. + +### Return Value + +text horizontal scale + +### Example + +
+ +--- + + +## setTextScaleX + +
+void setTextScaleX(SkScalar scaleX)
+
+ +Sets Text Scale X. +Default value is 1. + +### Parameters + + + +
scaleX +text horizontal scale
+ +### Example + +
+ +--- + +# Text Skew X +Text Skew X adjusts the text horizontal slant. +Text skewing approximates italic and oblique type faces when the actual face +is not available. +Text Skew X can be set to any value. +Text Skew X defaults to 0. + +### Example + +
+ + +## getTextSkewX + +
+SkScalar getTextSkewX() const
+
+ +Returns Text Skew X. +Default value is zero. + +### Return Value + +additional shear in x-axis relative to y-axis + +### Example + +
+ +--- + + +## setTextSkewX + +
+void setTextSkewX(SkScalar skewX)
+
+ +Sets Text Skew X. +Default value is zero. + +### Parameters + + + +
skewX +additional shear in x-axis relative to y-axis
+ +### Example + +
+ +--- + +# Text Encoding + +## Enum SkPaint::TextEncoding + +
+enum TextEncoding {
+kUTF8 TextEncoding,
+kUTF16 TextEncoding,
+kUTF32 TextEncoding,
+kGlyphID TextEncoding
+};
+ +TextEncoding determines whether text specifies character codes and their encoded size, +or glyph indices. Character codes use the encoding specified by theUnicode standardhttp://unicode.org/standard/standard.html. +Character codes encoded size are specified by UTF-8, UTF-16, or UTF-32. +All character encoding are able to represent all of Unicode, differing only +in the total storage required. + +UTF-8 (RFC 3629)https://tools.ietf.org/html/rfc3629is made up of 8-bit bytes, +and is a superset of ASCII. +UTF-16 (RFC 2781)https://tools.ietf.org/html/rfc2781is made up of 16-bit words, +and is a superset of Unicode ranges 0x0000 to 0xD7FF and 0xE000 to 0xFFFF. +UTF-32http://www.unicode.org/versions/Unicode5.0.0/ch03.pdfis +made up of 32-bit words, and is a superset of Unicode. + +Font Manager uses font data to convert character code points into glyph indices. +A glyph index is a 16-bit word. + +TextEncoding is set to kUTF8 TextEncoding by default. + +### Constants + + + + + + + + + + + + + + + +
SkPaint::kUTF8_TextEncoding 0Uses bytes to represent UTF-8 or ASCII.
SkPaint::kUTF16_TextEncoding 1Uses two byte words to represent most of Unicode.
SkPaint::kUTF32_TextEncoding 2Uses four byte words to represent all of Unicode.
SkPaint::kGlyphID_TextEncoding 3Uses two byte words to represent glyph indices.
+ +### Example + +
First line has UTF-8 encoding. +Second line has UTF-16 encoding. +Third line has UTF-32 encoding. +Fourth line has 16 bit glyph indices.
+ + +## getTextEncoding + +
+TextEncoding getTextEncoding() const
+
+ +Returns Text Encoding. +Text Encoding determines how character code points are mapped to font glyph indices. + +### Return Value + +one of: kUTF8 TextEncoding, kUTF16 TextEncoding, kUTF32 TextEncoding, or +kGlyphID TextEncoding + +### Example + +
+ +#### Example Output + +~~~~ +kUTF8_TextEncoding == text encoding +kGlyphID_TextEncoding == text encoding +~~~~ + +
+ +--- + + +## setTextEncoding + +
+void setTextEncoding(TextEncoding encoding)
+
+ +Sets Text Encoding to encoding. +Text Encoding determines how character code points are mapped to font glyph indices. +Invalid values for encoding are ignored. + +### Parameters + + + +
encoding +one of: kUTF8 TextEncoding, kUTF16 TextEncoding, kUTF32 TextEncoding, or
+ +### Example + +
+ +#### Example Output + +~~~~ +4 != text encoding +~~~~ + +
+ +--- + +# Font Metrics +Font Metrics describe dimensions common to the glyphs in Typeface. +The dimensions are computed by Font Manager from font data and do not take +Paint settings other than Text Size into account. + +Font dimensions specify the anchor to the left of the glyph at baseline as the origin. +X-axis values to the left of the glyph are negative, and to the right of the left glyph edge +are positive. +Y-axis values above the baseline are negative, and below the baseline are positive. + +### Example + +
+ +# Struct SkPaint::FontMetrics + +
+struct FontMetrics {
+enum FontMetricsFlags {
+kUnderlineThicknessIsValid Flag = 1 << 0,
+kUnderlinePositionIsValid Flag = 1 << 1,
+kStrikeoutThicknessIsValid Flag = 1 << 2,
+kStrikeoutPositionIsValid Flag = 1 << 3,
+};
+
+uint32_t    fFlags;
+SkScalar    fTop;
+SkScalar    fAscent;
+SkScalar    fDescent;
+SkScalar    fBottom;
+SkScalar    fLeading;
+SkScalar    fAvgCharWidth;
+SkScalar    fMaxCharWidth;
+SkScalar    fXMin;
+SkScalar    fXMax;
+SkScalar    fXHeight;
+SkScalar    fCapHeight;
+SkScalar    fUnderlineThickness;
+SkScalar    fUnderlinePosition;
+SkScalar    fStrikeoutThickness;
+SkScalar    fStrikeoutPosition;
+
+bool hasUnderlineThickness(SkScalar* thickness) const;
+bool hasUnderlinePosition(SkScalar* position) const;
+bool hasStrikeoutThickness(SkScalar* thickness) const;
+bool hasStrikeoutPosition(SkScalar* position) const;
+};
+ +FontMetrics is filled out by getFontMetrics. FontMetrics contents reflect the values +computed by Font Manager using Typeface. Values are set to zero if they are +not availble. + +fUnderlineThickness and fUnderlinePosition have a bit set in fFlags if their values +are valid, since their value may be zero. +fStrikeoutThickness and fStrikeoutPosition have a bit set in fFlags if their values +are valid, since their value may be zero. + +## Enum SkPaint::FontMetrics::FontMetricsFlags + +
+enum FontMetricsFlags {
+kUnderlineThicknessIsValid Flag = 1 << 0,
+kUnderlinePositionIsValid Flag = 1 << 1,
+kStrikeoutThicknessIsValid Flag = 1 << 2,
+kStrikeoutPositionIsValid Flag = 1 << 3,
+};
+ +FontMetricsFlags are set in fFlags when underline and strikeout metrics are valid; +the underline or strikeout metric may be valid and zero. +Fonts with embedded bitmaps may not have valid underline or strikeout metrics. + +### Constants + + + + + + + + + + + + + + + +
SkPaint::FontMetrics::kUnderlineThicknessIsValid_Flag 0x0001Set if fUnderlineThickness is valid.
SkPaint::FontMetrics::kUnderlinePositionIsValid_Flag 0x0002Set if fUnderlinePosition is valid.
SkPaint::FontMetrics::kStrikeoutThicknessIsValid_Flag 0x0004Set if fStrikeoutThickness is valid.
SkPaint::FontMetrics::kStrikeoutPositionIsValid_Flag 0x0008Set if fStrikeoutPosition is valid.
+ +uint32_t fFlags + +fFlags is set when underline metrics are valid. + +SkScalar fTop + +Largest height for any glyph. +A measure from the baseline, and is less than or equal to zero. + +SkScalar fAscent + +Recommended distance above the baseline to reserve for a line of text. +A measure from the baseline, and is less than or equal to zero. + +SkScalar fDescent + +Recommended distance below the baseline to reserve for a line of text. +A measure from the baseline, and is greater than or equal to zero. + +SkScalar fBottom + +Greatest extent below the baseline for any glyph. +A measure from the baseline, and is greater than or equal to zero. + +SkScalar fLeading + +Recommended distance to add between lines of text. +Greater than or equal to zero. + +SkScalar fAvgCharWidth + +Average character width, if it is available. +Zero if no average width is stored in the font. + +SkScalar fMaxCharWidth + +Maximum character width. + +SkScalar fXMin + +Minimum bounding box x value for all glyphs. +Typically less than zero. + +SkScalar fXMax + +Maximum bounding box x value for all glyphs. +Typically greater than zero. + +SkScalar fXHeight + +Height of a lower-case 'x'. +May be zero if no lower-case height is stored in the font. + +SkScalar fCapHeight + +Height of an upper-case letter. +May be zero if no upper-case height is stored in the font. + +SkScalar fUnderlineThickness + +Underline thickness. If the metric +is valid, the kUnderlineThicknessIsValid Flag is set in fFlags. +If kUnderlineThicknessIsValid Flag is clear, fUnderlineThickness is zero. + +SkScalar fUnderlinePosition + +Underline position relative to the baseline. +It may be negative, to draw the underline above the baseline, zero +to draw the underline on the baseline, or positive to draw the underline +below the baseline. + +If the metric is valid, the kUnderlinePositionIsValid Flag is set in fFlags. +If kUnderlinePositionIsValid Flag is clear, fUnderlinePosition is zero. + +SkScalar fStrikeoutThickness + +Strikeout thickness. If the metric +is valid, the kStrikeoutThicknessIsValid Flag is set in fFlags. +If kStrikeoutThicknessIsValid Flag is clear, fStrikeoutThickness is zero. + +SkScalar fStrikeoutPosition + +Strikeout position relative to the baseline. +It may be negative, to draw the strikeout above the baseline, zero +to draw the strikeout on the baseline, or positive to draw the strikeout +below the baseline. + +If the metric is valid, the kStrikeoutPositionIsValid Flag is set in fFlags. +If kStrikeoutPositionIsValid Flag is clear, fStrikeoutPosition is zero. + + +## hasUnderlineThickness + +
+bool hasUnderlineThickness(SkScalar* thickness) const
+
+ +If Font Metrics has a valid underline thickness, return true, and set +thickness to that value. If it doesn't, return false, and ignore +thickness. + +### Parameters + + + +
thickness +storage for underline width
+ +### Return Value + +true if font specifies underline width + +--- + + +## hasUnderlinePosition + +
+bool hasUnderlinePosition(SkScalar* position) const
+
+ +If Font Metrics has a valid underline position, return true, and set +position to that value. If it doesn't, return false, and ignore +position. + +### Parameters + + + +
position +storage for underline position
+ +### Return Value + +true if font specifies underline position + +--- + + +## hasStrikeoutThickness + +
+bool hasStrikeoutThickness(SkScalar* thickness) const
+
+ +If Font Metrics has a valid strikeout thickness, return true, and set +thickness to that value. If it doesn't, return false, and ignore +thickness. + +### Parameters + + + +
thickness +storage for strikeout width
+ +### Return Value + +true if font specifies strikeout width + +--- + + +## hasStrikeoutPosition + +
+bool hasStrikeoutPosition(SkScalar* position) const
+
+ +If Font Metrics has a valid strikeout position, return true, and set +position to that value. If it doesn't, return false, and ignore +position. + +### Parameters + + + +
position +storage for strikeout position
+ +### Return Value + +true if font specifies strikeout position + +--- + + +## getFontMetrics + +
+SkScalar getFontMetrics(FontMetrics* metrics, SkScalar scale = 0) const
+
+ +Returns Font Metrics associated with Typeface. +The return value is the recommended spacing between lines: the sum of metrics +descent, ascent, and leading. +If metrics is not nullptr, Font Metrics is copied to metrics. +Results are scaled by Text Size but does not take into account +dimensions required by Text Scale X, Text Skew X, Fake Bold, +Style Stroke, and Path Effect. +Results can be additionally scaled by scale; a scale of zero +is ignored. + +### Parameters + + + + +
metrics +storage for Font Metrics from Typeface; may be nullptr
scale +additional multiplier for returned values
+ +### Return Value + +recommended spacing between lines + +### Example + +
+ +### See Also + +Text Size Typeface Typeface Methods + +--- + + +## getFontSpacing + +
+SkScalar getFontSpacing() const
+
+ +Returns the recommended spacing between lines: the sum of metrics +descent, ascent, and leading. +Result is scaled by Text Size but does not take into account +dimensions required by stroking and Path Effect. +getFontSpacing returns the same result as getFontMetrics. + +### Return Value + +recommended spacing between lines + +### Example + +
+ +#### Example Output + +~~~~ +textSize: 12 fontSpacing: 13.9688 +textSize: 18 fontSpacing: 20.9531 +textSize: 24 fontSpacing: 27.9375 +textSize: 32 fontSpacing: 37.25 +~~~~ + +
+ +--- + + +## getFontBounds + +
+SkRect getFontBounds() const
+
+ +Returns the union of bounds of all glyphs. +Returned dimensions are computed by Font Manager from font data, +ignoring Hinting. getFontBounds includes Text Size, Text Scale X, +and Text Skew X, but not Fake Bold or Path Effect. + +If Text Size is large, Text Scale X is one, and Text Skew X is zero, +getFontBounds returns the same bounds as Font Metrics { FontMetrics::fXMin, +FontMetrics::fTop, FontMetrics::fXMax, FontMetrics::fBottom }. + +### Return Value + +union of bounds of all glyphs + +### Example + +
+ +#### Example Output + +~~~~ +metrics bounds = { -12.2461, -14.7891, 21.5215, 5.55469 } +font bounds = { -12.2461, -14.7891, 21.5215, 5.55469 } +~~~~ + +
+ +--- + + +## textToGlyphs + +
+int textToGlyphs(const void* text, size_t byteLength, SkGlyphID glyphs[]) const
+
+ +Converts text into glyph indices. +Returns the number of glyph indices represented by text. +Text Encoding specifies how text represents characters or glyphs. +glyphs may be nullptr, to compute the glyph count. + +Does not check text for valid character encoding or valid +glyph indices. + +If byteLength equals zero, textToGlyphs returns zero. +If byteLength includes a partial character, the partial character is ignored. + +If Text Encoding is kUTF8 TextEncoding and +text contains an invalid UTF-8 sequence, zero is returned. + +### Parameters + + + + + +
text +character stroage encoded with Text Encoding
byteLength +length of character storage in bytes
glyphs +storage for glyph indices; may be nullptr
+ +### Return Value + +number of glyphs represented by text of length byteLength + +### Example + +
+ +--- + + +## countText + +
+int countText(const void* text, size_t byteLength) const
+
+ +Returns the number of glyphs in text. +Uses Text Encoding to count the glyphs. +Returns the same result as textToGlyphs. + +### Parameters + + + + +
text +character stroage encoded with Text Encoding
byteLength +length of character storage in bytes
+ +### Return Value + +number of glyphs represented by text of length byteLength + +### Example + +
+ +#### Example Output + +~~~~ +count = 5 +~~~~ + +
+ +--- + + +## containsText + +
+bool containsText(const void* text, size_t byteLength) const
+
+ +Returns true if all text corresponds to a non-zero glyph index. +Returns false if any characters in text are not supported in +Typeface. + +If Text Encoding is kGlyphID TextEncoding, containsText +returns true if all glyph indices in text are non-zero; containsText +does not check to see if text contains valid glyph indices for Typeface. + +Returns true if bytelength is zero. + +### Parameters + + + + +
text +array of characters or glyphs
byteLength +number of bytes in text array
+ +### Return Value + +true if all text corresponds to a non-zero glyph index + +### Example + +
containsText succeeds for degree symbol, but cannot find a glyph index +corresponding to the Unicode surrogate code point.
+ +#### Example Output + +~~~~ +0x00b0 == has char +0xd800 != has char +~~~~ + +
+ +### Example + +
containsText returns true that glyph index is greater than zero, not +that it corresponds to an entry in Typeface.
+ +#### Example Output + +~~~~ +0x01ff == has glyph +0x0000 != has glyph +0xffff == has glyph +~~~~ + +
+ +### See Also + +setTextEncoding Typeface + +--- + + +## glyphsToUnichars + +
+void glyphsToUnichars(const SkGlyphID glyphs[], int count, SkUnichar text[]) const
+
+ +Converts glyphs into text if possible. +Glyph values without direct Unicode equivalents are mapped to zero. +Uses the Typeface, but is unaffected +by Text Encoding; the text values returned are equivalent to kUTF32 TextEncoding. + +Only supported on platforms that use FreeType as the Font Engine. + +### Parameters + + + + + +
glyphs +array of indices into font
count +length of glyph array
text +storage for character codes, one per glyph
+ +### Example + +
Convert UTF-8 text to glyphs; then convert glyphs to Unichar code points.
+ +--- + +# Measure Text + + +## measureText + +
+SkScalar measureText(const void* text, size_t length, SkRect* bounds) const
+
+ +Returns the advance width of text if kVerticalText Flag is clear, +and the height of text if kVerticalText Flag is set. +The advance is the normal distance to move before drawing additional text. +Uses Text Encoding to decode text, Typeface to get the font metrics, +and Text Size, Text Scale X, Text Skew X, Stroke Width, and +Path Effect to scale the metrics and bounds. +Returns the bounding box of text if bounds is not nullptr. +The bounding box is computed as if the text was drawn at the origin. + +### Parameters + + + + + +
text +character codes or glyph indices to be measured
length +number of bytes of text to measure
bounds +returns bounding box relative to (0, 0) if not nullptr
+ +### Return Value + +advance width or height + +### Example + +
+ +--- + +
+SkScalar measureText(const void* text, size_t length) const
+
+ +Returns the advance width of text if kVerticalText Flag is clear, +and the height of text if kVerticalText Flag is set. +The advance is the normal distance to move before drawing additional text. +Uses Text Encoding to decode text, Typeface to get the font metrics, +and Text Size to scale the metrics. +Does not scale the advance or bounds by Fake Bold or Path Effect. + +### Parameters + + + + +
text +character codes or glyph indices to be measured
length +number of bytes of text to measure
+ +### Return Value + +advance width or height + +### Example + +
+ +#### Example Output + +~~~~ +default width = 5 +double width = 10 +~~~~ + +
+ +--- + + +## breakText + +
+size_t breakText(const void* text, size_t length, SkScalar maxWidth,
+                 SkScalar* measuredWidth = NULL) const
+
+ +Returns the bytes of text that fit within maxWidth. +If kVerticalText Flag is clear, the text fragment fits if its advance width is less than or +equal to maxWidth. +If kVerticalText Flag is set, the text fragment fits if its advance height is less than or +equal to maxWidth. +Measures only while the advance is less than or equal to maxWidth. +Returns the advance or the text fragment in measuredWidth if it not nullptr. +Uses Text Encoding to decode text, Typeface to get the font metrics, +and Text Size to scale the metrics. +Does not scale the advance or bounds by Fake Bold or Path Effect. + +### Parameters + + + + + + +
text +character codes or glyph indices to be measured
length +number of bytes of text to measure
maxWidth +advance limit; text is measured while advance is less than maxWidth
measuredWidth +returns the width of the text less than or equal to maxWidth
+ +### Return Value + +bytes of text that fit, always less than or equal to length + +### Example + +
Line under "" shows desired width, shorter than available characters. +Line under "" shows measured width after breaking text.
+ +--- + + +## getTextWidths + +
+int getTextWidths(const void* text, size_t byteLength, SkScalar widths[],
+                  SkRect bounds[] = NULL) const
+
+ +Retrieves the advance and bounds for each glyph in text, and returns +the glyph count in text. +Both widths and bounds may be nullptr. +If widths is not nullptr, widths must be an array of glyph count entries. +if bounds is not nullptr, bounds must be an array of glyph count entries. +If kVerticalText Flag is clear, widths returns the horizontal advance. +If kVerticalText Flag is set, widths returns the vertical advance. +Uses Text Encoding to decode text, Typeface to get the font metrics, +and Text Size to scale the widths and bounds. +Does not scale the advance by Fake Bold or Path Effect. +Does include Fake Bold and Path Effect in the bounds. + +### Parameters + + + + + + +
text +character codes or glyph indices to be measured
byteLength +number of bytes of text to measure
widths +returns text advances for each glyph; may be nullptr
bounds +returns bounds for each glyph relative to (0, 0); may be nullptr
+ +### Return Value + +glyph count in text + +### Example + +
Bounds of glyphs increase for stroked text, but text advance remains the same. +The underlines show the text advance, spaced to keep them distinct.
+ +--- + +# Text Path +Text Path describes the geometry of glyphs used to draw text. + + +## getTextPath + +
+void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y,
+                 SkPath* path) const
+
+ +Returns the geometry as Path equivalent to the drawn text. +Uses Text Encoding to decode text, Typeface to get the glyph paths, +and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths. +All of the glyph paths are stored in path. +getTextPath uses x, y, and Text Align to position path. + +### Parameters + + + + + + + +
text +character codes or glyph indices
length +number of bytes of text
x +x-coordinate of the origin of the text
y +y-coordinate of the origin of the text
path +geometry of the glyphs
+ +### Example + +
Text is added to Path, offset, and subtracted from Path, then added at +the offset location. The result is rendered with one draw call.
+ +--- + + +## getPosTextPath + +
+void getPosTextPath(const void* text, size_t length, const SkPoint pos[],
+                    SkPath* path) const
+
+ +Returns the geometry as Path equivalent to the drawn text. +Uses Text Encoding to decode text, Typeface to get the glyph paths, +and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths. +All of the glyph paths are stored in path. +Uses pos array and Text Align to position path. +pos contains a position for each glyph. + +### Parameters + + + + + + +
text +character codes or glyph indices
length +number of bytes of text
pos +positions of each glyph
path +geometry of the glyphs
+ +### Example + +
Simplifies three glyphs to eliminate overlaps, and strokes the result.
+ +--- + +# Text Intercepts +Text Intercepts describe the intersection of drawn text glyphs with a pair +of lines parallel to the text advance. Text Intercepts permits creating a +underline that skips descenders. + + +## getTextIntercepts + +
+int getTextIntercepts(const void* text, size_t length, SkScalar x, SkScalar y,
+                      const SkScalar bounds[2], SkScalar* intervals) const
+
+ +Returns the number of intervals that intersect bounds. +bounds describes a pair of lines parallel to the text advance. +The return count is zero or a multiple of two, and is at most twice the number of glyphs in +the string. +Uses Text Encoding to decode text, Typeface to get the glyph paths, +and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths. +Uses x, y, and Text Align to position intervals. +Pass nullptr for intervals to determine the size of the interval array. +intervals are cached to improve performance for multiple calls. + +### Parameters + + + + + + + + +
text +character codes or glyph indices
length +number of bytes of text
x +x-coordinate of the origin of the text
y +y-coordinate of the origin of the text
bounds +lower and upper line parallel to the advance
intervals +returned intersections; may be nullptr
+ +### Return Value + +number of intersections; may be zero + +### Example + +
Underline uses intercepts to draw on either side of the glyph descender.
+ +--- + + +## getPosTextIntercepts + +
+int getPosTextIntercepts(const void* text, size_t length, const SkPoint pos[],
+                         const SkScalar bounds[2], SkScalar* intervals) const
+
+ +Returns the number of intervals that intersect bounds. +bounds describes a pair of lines parallel to the text advance. +The return count is zero or a multiple of two, and is at most twice the number of glyphs in +the string. +Uses Text Encoding to decode text, Typeface to get the glyph paths, +and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths. +Uses pos array and Text Align to position intervals. +Pass nullptr for intervals to determine the size of the interval array. +intervals are cached to improve performance for multiple calls. + +### Parameters + + + + + + + +
text +character codes or glyph indices
length +number of bytes of text
pos +positions of each glyph
bounds +lower and upper line parallel to the advance
intervals +returned intersections; may be nullptr
+ +### Return Value + +The number of intersections; may be zero + +### Example + +
Text intercepts draw on either side of, but not inside, glyphs in a run.
+ +--- + + +## getPosTextHIntercepts + +
+int getPosTextHIntercepts(const void* text, size_t length, const SkScalar xpos[],
+                          SkScalar constY, const SkScalar bounds[2],
+                          SkScalar* intervals) const
+
+ +Returns the number of intervals that intersect bounds. +bounds describes a pair of lines parallel to the text advance. +The return count is zero or a multiple of two, and is at most twice the number of glyphs in +the string. +Uses Text Encoding to decode text, Typeface to get the glyph paths, +and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths. +Uses xpos array, constY, and Text Align to position intervals. +Pass nullptr for intervals to determine the size of the interval array. +intervals are cached to improve performance for multiple calls. + +### Parameters + + + + + + + + +
text +character codes or glyph indices
length +number of bytes of text
xpos +positions of each glyph in x
constY +position of each glyph in y
bounds +lower and upper line parallel to the advance
intervals +returned intersections; may be nullptr
+ +### Return Value + +number of intersections; may be zero + +### Example + +
Text intercepts do not take stroke thickness into consideration.
+ +--- + + +## getTextBlobIntercepts + +
+int getTextBlobIntercepts(const SkTextBlob* blob, const SkScalar bounds[2],
+                          SkScalar* intervals) const
+
+ +Returns the number of intervals that intersect bounds. +bounds describes a pair of lines parallel to the text advance. +The return count is zero or a multiple of two, and is at most twice the number of glyphs in +the string. +Uses Text Encoding to decode text, Typeface to get the glyph paths, +and Text Size, Fake Bold, and Path Effect to scale and modify the glyph paths. +Uses pos array and Text Align to position intervals. +Pass nullptr for intervals to determine the size of the interval array. +intervals are cached to improve performance for multiple calls. + +### Parameters + + + + + +
blob +glyphs, positions, and text paint attributes
bounds +lower and upper line parallel to the advance
intervals +returned intersections; may be nullptr
+ +### Return Value + +number of intersections; may be zero + +### Example + +
+ +--- + + +## nothingToDraw + +
+bool nothingToDraw() const
+
+ +Returns true if Paint prevents all drawing. +If nothingToDraw returns false, the Paint may or may not allow drawing. + +Returns true if Blend Mode and Color Alpha are enabled, +and computed Color Alpha is zero. + +### Return Value + +true if Paint prevents all drawing + +### Example + +
+ +#### Example Output + +~~~~ +initial nothing to draw: false +blend dst nothing to draw: true +blend src over nothing to draw: false +alpha 0 nothing to draw: true +~~~~ + +
+ +--- + +# Fast Bounds +Fast Bounds methods conservatively outset a drawing bounds by additional area +Paint may draw to. + + +## canComputeFastBounds + +
+bool canComputeFastBounds() const
+
+ +Returns true if Paint does not include elements requiring extensive computation +to compute Device bounds of drawn geometry. For instance, Paint with Path Effect +always returns false. + +### Return Value + +true if Paint allows for fast computation of bounds + +--- + + +## computeFastBounds + +
+const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const
+
+ +Only call this if canComputeFastBounds returned true. This takes a +raw rectangle (the raw bounds of a shape), and adjusts it for stylistic +effects in the paint (e.g. stroking). If needed, it uses the storage +rect parameter. It returns the adjusted bounds that can then be used +for SkCanvas::quickReject tests. + +The returned rect will either be orig or storage, thus the caller +should not rely on storage being set to the result, but should always +use the retured value. It is legal for orig and storage to be the same +rect. + +### Parameters + + + + +
orig +geometry modified by Paint when drawn
storage +computed bounds of geometry; may not be nullptr
+ +### Return Value + +fast computed bounds + +--- + + +## computeFastStrokeBounds + +
+const SkRect& computeFastStrokeBounds(const SkRect& orig, SkRect* storage) const
+
+ +### Parameters + + + + +
orig +geometry modified by Paint when drawn
storage +computed bounds of geometry
+ +### Return Value + +fast computed bounds + +--- + + +## doComputeFastBounds + +
+const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage,
+                                  Style style) const
+
+ +Take the style explicitly, so the caller can force us to be stroked +without having to make a copy of the paint just to change that field. + +### Parameters + + + + + +
orig +geometry modified by Paint when drawn
storage +computed bounds of geometry
style +overrides Style
+ +### Return Value + +fast computed bounds + +--- + + +## toString + +
+void toString(SkString* str) const;
+
+ +Converts Paint to machine parsable form in developer mode. + +### Parameters + + + +
str +storage for string containing parsable Paint
+ +### Example + +
+ +#### Example Output + +~~~~ +text size = 12 +~~~~ + +
+ +--- + diff --git a/site/user/api/SkPath_Reference.md b/site/user/api/SkPath_Reference.md new file mode 100644 index 0000000000..c4eb275438 --- /dev/null +++ b/site/user/api/SkPath_Reference.md @@ -0,0 +1,4975 @@ +SkPath Reference +=== + +# Path +Path contains Lines and Curves which can be stroked or filled. Contour is +composed of a series of connected Lines and Curves. Path may contain zero, +one, or more Contours. +Each Line and Curve are described by Verb, Points, and optional Weight. + +Each pair of connected Lines and Curves share common Point; for instance, Path +containing two connected Lines are described the Verb sequence: +SkPath::kMove Verb, SkPath::kLine Verb, SkPath::kLine Verb; and a Point sequence +with three entries, sharing +the middle entry as the end of the first Line and the start of the second Line. + +Path components Arc, Rect, Round Rect, Circle, and Oval are composed of +Lines and Curves with as many Verbs and Points required +for an exact description. Once added to Path, these components may lose their +identity; although Path can be inspected to determine if it decribes a single +Rect, Oval, Round Rect, and so on. + +### Example + +
Path contains three Contours: Line, Circle, and Quad. Line is stroked but +not filled. Circle is stroked and filled; Circle stroke forms a loop. Quad +is stroked and filled, but since it is not closed, Quad does not stroke a loop.
+ +Path contains a Fill Type which determines whether overlapping Contours +form fills or holes. Fill Type also determines whether area inside or outside +Lines and Curves is filled. + +### Example + +
Path is drawn filled, then stroked, then stroked and filled.
+ +Path contents are never shared. Copying Path by value effectively creates +a new Path independent of the original. Internally, the copy does not duplicate +its contents until it is edited, to reduce memory use and improve performance. + +## Subtopics + +| topics | description | +| --- | --- | + +## Contour + +Contour contains one or more Verbs, and as many Points as +are required to satisfy Verb Array. First Verb in Path is always +SkPath::kMove Verb; each SkPath::kMove Verb that follows starts a new Contour. + +### Example + +
Each SkPath::moveTo starts a new Contour, and content after SkPath::close() +also starts a new Contour. Since SkPath::conicTo wasn't preceded by +SkPath::moveTo, the first Point of the third Contour starts at the last Point +of the second Contour.
+ +If final Verb in Contour is SkPath::kClose Verb, Line connects Last Point in +Contour with first Point. A closed Contour, stroked, draws +Paint Stroke Join at Last Point and first Point. Without SkPath::kClose Verb +as final Verb, Last Point and first Point are not connected; Contour +remains open. An open Contour, stroked, draws Paint Stroke Cap at +Last Point and first Point. + +### Example + +
Path is drawn stroked, with an open Contour and a closed Contour.
+ +## Zero Length + +Contour length is distance traveled from first Point to Last Point, +plus, if Contour is closed, distance from Last Point to first Point. +Even if Contour length is zero, stroked Lines are drawn if Paint Stroke Cap +makes them visible. + +### Example + +
+ +# Class SkPath + +# Overview + +## Constants + +| constants | description | +| --- | --- | +| AddPathMode | Sets addPath options. | +| ArcSize | Sets arcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc, Direction sweep, SkScalar x, SkScalar y) options. | +| Convexity | Returns if Path is convex or concave. | +| Direction | Sets Contour clockwise or counterclockwise. | +| FillType | Sets winding rule and inverse fill. | +| SegmentMask | +Verb| Controls how Path Points are interpreted. | + +## Classes and Structs + +| class or struct | description | +| --- | --- | +| Iter | Iterates through lines and curves, skipping degenerates. | +| RawIter | Iterates through lines and curves, including degenerates. | + +## Constructors + +| | description | +| --- | --- | +| SkPath() | Constructs with default values. | +| SkPath(const SkPath& path) | Makes a shallow copy. | +| | Decreases Reference Count of owned objects. | + +## Operators + +| operator | description | +| --- | --- | +| operator=(const SkPath& path) | Makes a shallow copy. | +| operator==(const SkPath& a, const SkPath& b) | Compares paths for equality. | +| operator!=(const SkPath& a, const SkPath& b) | Compares paths for inequality. | + +## Member Functions + +| function | description | +| --- | --- | +| ConvertConicToQuads | Approximates Conic with Quad array. | +| ConvertToNonInverseFillType | Returns Fill Type representing inside geometry. | +| IsCubicDegenerate | Returns if Cubic is very small. | +| IsInverseFillType | Returns if Fill Type represents outside geometry. | +| IsLineDegenerate | Returns if Line is very small. | +| IsQuadDegenerate | Returns if Quad is very small. | +| addArc | Adds one Contour containing Arc. | +| addCircle | Adds one Contour containing Circle. | +| addOval | Adds one Contour containing Oval. | +| addPath | Adds contents of Path. | +| addPoly | Adds one Contour containing connected lines. | +| addRRect | Adds one Contour containing Round Rect. | +| addRect | Adds one Contour containing Rect. | +| addRoundRect | Adds one Contour containing Round Rect with common corner radii. | +| arcTo | Appends Arc. | +| close | Makes last Contour a loop. | +| computeTightBounds | Returns extent of geometry. | +| conicTo | Appends Conic. | +| conservativelyContainsRect | Returns true if Rect may be inside. | +| contains | Returns if Point is in fill area. | +| countPoints | Returns Point Array length. | +| countVerbs | Returns Verb Array length. | +| cubicTo | Appends Cubic. | +| dump | Sends text representation using floats to stdout. | +| dumpHex | Sends text representation using hexadecimal to stdout. | +| experimentalValidateRef | Experimental; debugging only. | +| getBounds | Returns maximum and minimum of Point Array. | +| getConvexity | Returns geometry convexity, computing if necessary. | +| getConvexityOrUnknown | Returns geometry convexity if known. | +| getFillType | Returns Fill Type: winding, even-odd, inverse. | +| getGenerationID | Returns unique ID. | +| getLastPt | Returns Last Point. | +| getPoint | Returns entry from Point Array. | +| getPoints | Returns Point Array. | +| getSegmentMasks | Returns types in Verb Array. | +| getVerbs | Returns Verb Array. | +| incReserve | Hint to reserve space for additional data. | +| interpolate | Interpolates between Path pair. | +| isConvex | Returns if geometry is convex. | +| isEmpty | Returns if verb count is zero. | +| isFinite | Returns if all Point values are finite. | +| isInterpolatable | Returns if pair contains equal counts of Verb Array and Weights. | +| isInverseFillType | Returns if Fill Type fills outside geometry. | +| isLastContourClosed | Returns if final Contour forms a loop. | +| isLine | Returns if describes Line. | +| isNestedFillRects | Returns if describes Rect pair, one inside the other. | +| isOval | Returns if describes Oval. | +| isRRect | Returns if describes Round Rect. | +| isRect | Returns if describes Rect. | +| isVolatile | Returns if Device should not cache. | +| lineTo | Appends Line. | +| moveTo | Starts Contour. | +| offset | Translates Point Array. | +| quadTo | Appends Quad. | +| rArcTo | Appends Arc relative to Last Point. | +| rConicTo | Appends Conic relative to Last Point. | +| rCubicTo | Appends Cubic relative to Last Point. | +| rLineTo | Appends Line relative to Last Point. | +| rMoveTo | Starts Contour relative to Last Point. | +| rQuadTo | Appends Quad relative to Last Point. | +| readFromMemory | Initialize from buffer. | +| reset | Removes Verb Array, Point Array, and Weights; frees memory. | +| reverseAddPath | Adds contents of Path back to front. | +| rewind | Removes Verb Array, Point Array, and Weights; leaves memory allocated. | +| setConvexity | Sets if geometry is convex to avoid future computation. | +| setFillType | Sets Fill Type: winding, even-odd, inverse. | +| setIsConvex | Deprecated. | +| setIsVolatile | Sets if Device should not cache. | +| setLastPt | Replaces Last Point. | +| swap | Exchanges Path pair. | +| toggleInverseFillType | Toggles Fill Type between inside and outside geometry. | +| transform | Applies Matrix to Point Array and Weights. | +| unique | Returns if data has single owner. | +| updateBoundsCache | Refresh result of getBounds. | +| writeToMemory | Copy data to buffer. | + +## Verb + +## Enum SkPath::Verb + +
+enum Verb {
+kMove Verb 
+kLine Verb 
+kQuad Verb 
+kConic Verb 
+kCubic Verb 
+kClose Verb 
+kDone Verb 
+};
+ +Verb instructs Path how to interpret one or more Point and optional Weight; +manage Contour, and terminate Path. + +### Constants + + + + + + + + + + + + + + + + + + + + + + + +Each Verb has zero or more Points stored in Path. +Path iterator returns complete curve descriptions, duplicating shared Points +for consecutive entries. + +
SkPath::kMove_Verb 0Starts new Contour at next Point.
SkPath::kLine_Verb 1Adds Line from Last Point to next Point. +Line is a straight segment from Point to Point.
SkPath::kQuad_Verb 2Adds Quad from Last Point, using control Point, and end Point. +Quad is a parabolic section within tangents from Last Point to control Point, +and control Point to end Point.
SkPath::kConic_Verb 3Adds Conic from Last Point, using control Point, end Point, and Weight. +Conic is a elliptical, parabolic, or hyperbolic section within tangents +from Last Point to control Point, and control Point to end Point, constrained +by Weight. Weight less than one is elliptical; equal to one is parabolic +(and identical to Quad); greater than one hyperbolic.
SkPath::kCubic_Verb 4Adds Cubic from Last Point, using two control Points, and end Point. +Cubic is a third-order Bezier section within tangents from Last Point to +first control Point, and from second control Point to end Point.
SkPath::kClose_Verb 5Closes Contour, connecting Last Point to kMove Verb Point.
SkPath::kDone_Verb 6Terminates Path. Not in Verb Array, but returned by Path iterator.
+ +| Verb | Allocated Points | Iterated Points | Weights | +| --- | --- | --- | --- | +| kMove Verb | 1 | 1 | 0 | +| kLine Verb | 1 | 2 | 0 | +| kQuad Verb | 2 | 3 | 0 | +| kConic Verb | 2 | 3 | 1 | +| kCubic Verb | 3 | 4 | 0 | +| kClose Verb | 0 | 1 | 0 | +| kDone Verb | -- | 0 | 0 | + +### Example + +
+ +#### Example Output + +~~~~ +verb count: 7 +verbs: kMove_Verb kLine_Verb kQuad_Verb kClose_Verb kMove_Verb kCubic_Verb kConic_Verb +~~~~ + +
+ + + +## Direction + +## Enum SkPath::Direction + +
+enum Direction {
+kCW Direction 
+kCCW Direction 
+};
+ +Direction describes whether Contour is clockwise or counterclockwise. +When Path contains multiple overlapping Contours, Direction together with +Fill Type determines whether overlaps are filled or form holes. + +Direction also determines how Contour is measured. For instance, dashing +measures along Path to determine where to start and stop stroke; Direction +will change dashed results as it steps clockwise or counterclockwise. + +Closed Contours like Rect, Round Rect, Circle, and Oval added with +kCW Direction travel clockwise; the same added with kCCW Direction +travel counterclockwise. + +### Constants + + + + + + + + +
SkPath::kCW_Direction Contour travels in a clockwise direction.
SkPath::kCCW_Direction Contour travels in a counterclockwise direction.
+ +### Example + +
+ +### See Also + +arcTo rArcTo isRect isNestedFillRects addRect addOval + + + + +## SkPath + +
+SkPath()
+
+ +By default, Path has no Verbs, no Points, and no Weights. +Fill Type is set to kWinding FillType. + +### Return Value + +empty Path. + +### Example + +
+ +#### Example Output + +~~~~ +path is empty +~~~~ + +
+ +### See Also + +reset rewind + +--- + + +## SkPath + +
+SkPath(const SkPath& path)
+
+ +Copy constructor makes two paths identical by value. Internally, path and +the returned result share pointer values. The underlying Verb Array, Point Array +and Weights are copied when modified. + +Creating a Path copy is very efficient and never allocates memory. +Paths are always copied by value from the interface; the underlying shared +pointers are not exposed. + +### Parameters + + + +
path +Path to copy by value.
+ +### Return Value + +Copy of Path. + +### Example + +
Modifying one path does not effect another, even if they started as copies +of each other.
+ +#### Example Output + +~~~~ +path verbs: 2 +path2 verbs: 3 +after reset +path verbs: 0 +path2 verbs: 3 +~~~~ + +
+ +### See Also + +operator=(const SkPath& path) + +--- + + +## ~SkPath + +
+~SkPath()
+
+ +Releases ownership of any shared data and deletes data if Path is sole owner. + +### Example + +
delete calls Path destructor, but copy of original in path2 is unaffected.
+ +### See Also + +SkPath() SkPath(const SkPath& path) operator=(const SkPath& path) + +--- + + +## operator= + +
+SkPath& operator=(const SkPath& path)
+
+ +Path assignment makes two paths identical by value. Internally, assignment +shares pointer values. The underlying Verb Array, Point Array and Weights +are copied when modified. + +Copying Paths by assignment is very efficient and never allocates memory. +Paths are always copied by value from the interface; the underlying shared +pointers are not exposed. + +### Parameters + + + +
path +Verb Array, Point Array, Weights, amd Fill Type to copy.
+ +### Return Value + +Path copied by value. + +### Example + +
+ +#### Example Output + +~~~~ +path1 bounds = 10, 20, 30, 40 +path2 bounds = 10, 20, 30, 40 +~~~~ + +
+ +### See Also + +swap SkPath(const SkPath& path) + +--- + + +## operator== + +
+friend SK_API bool operator==(const SkPath& a, const SkPath& b)
+
+ +Compares a and b; returns true if Fill Type, Verb Array, Point Array, and Weights +are equivalent. + +### Parameters + + + + +
a +Path to compare.
b +Path to compare.
+ +### Return Value + +true if Path pair are equivalent. + +### Example + +
Rewind removes Verb Array but leaves storage; since storage is not compared, +Path pair are equivalent.
+ +#### Example Output + +~~~~ +empty one == two +moveTo one != two +rewind one == two +reset one == two +~~~~ + +
+ +--- + + +## operator!= + +
+friend bool operator!=(const SkPath& a, const SkPath& b)
+
+ +Compares a and b; returns true if Fill Type, Verb Array, Point Array, and Weights +are not equivalent. + +### Parameters + + + + +
a +Path to compare.
b +Path to compare.
+ +### Return Value + +true if Path pair are not equivalent. + +### Example + +
Path pair are equal though their convexity is not equal.
+ +#### Example Output + +~~~~ +empty one == two +addRect one == two +setConvexity one == two +convexity != +~~~~ + +
+ +--- + + +## isInterpolatable + +
+bool isInterpolatable(const SkPath& compare) const
+
+ +Return true if Paths contain equal Verbs and equal Weights. +If Paths contain one or more Conics, the Weights must match. + +conicTo may add different Verbs depending on Conic Weight, so it is not +trival to interpolate a pair of Paths containing Conics with different +Conic Weight values. + +### Parameters + + + +
compare +Path to compare.
+ +### Return Value + +true if Paths Verb Array and Weights are equivalent. + +### Example + +
+ +#### Example Output + +~~~~ +paths are interpolatable +~~~~ + +
+ +### See Also + +isInterpolatable + +--- + + +## interpolate + +
+bool interpolate(const SkPath& ending, SkScalar weight, SkPath* out) const
+
+ +Interpolate between Paths with equal sized Point Arrays. +Copy Verb Array and Weights to out, +and set out Point Array to a weighted average of this Point Array and ending +Point Array, using the formula: +(this->points * weight) + ending->points * (1 - weight)interpolate returns false and leaves out unchanged if Point Array is not +the same size as ending Point Array. Call isInterpolatable to check Path +compatibility prior to calling interpolate. + +### Parameters + + + + + +
ending +Point Array averaged with this Point Array.
weight +Most useful when between zero (ending Point Array) and +one (this Point Array); will work with values outside of this +range.
out +
+ +### Return Value + +true if Paths contain same number of Points. + +### Example + +
+ +### See Also + +isInterpolatable + +--- + + +## unique + +
+bool unique() const
+
+ +### Return Value + +true if Path has one owner. + +--- + +## Fill Type + +## Enum SkPath::FillType + +
+enum FillType {
+kWinding FillType 
+kEvenOdd FillType 
+kInverseWinding FillType 
+kInverseEvenOdd FillType 
+};
+ +Fill Type selects the rule used to fill Path. Path set to kWinding FillType +fills if the sum of Contour edges is not zero, where clockwise edges add one, and +counterclockwise edges subtract one. Path set to kEvenOdd FillType fills if the +number of Contour edges is odd. Each Fill Type has an inverse variant that +reverses the rule: +kInverseWinding FillType fills where the sum of Contour edges is zero; +kInverseEvenOdd FillType fills where the number of Contour edges is even. + +### Example + +
The top row has two clockwise rectangles. The second row has one clockwise and +one counterclockwise rectangle. The even-odd variants draw the same. The +winding variants draw the top rectangle overlap, which has a winding of 2, the +same as the outer parts of the top rectangles, which have a winding of 1.
+ +### Constants + + + + + + + + + + + + + + +
SkPath::kWinding_FillType Specifies fill as area is enclosed by a non-zero sum of Contour Directions.
SkPath::kEvenOdd_FillType Specifies fill as area enclosed by an odd number of Contours.
SkPath::kInverseWinding_FillType Specifies fill as area is enclosed by a zero sum of Contour Directions.
SkPath::kInverseEvenOdd_FillType Specifies fill as area enclosed by an even number of Contours.
+ +### Example + +
+ +### See Also + +SkPaint::Style Direction getFillType setFillType + + + + +## getFillType + +
+FillType getFillType() const
+
+ +Returns FillType, the rule used to fill Path. FillType of a new Path is +kWinding FillType. + +### Return Value + +one of: kWinding FillType, kEvenOdd FillType, kInverseWinding FillType, +kInverseEvenOdd FillType. + +### Example + +
+ +#### Example Output + +~~~~ +default path fill type is kWinding_FillType +~~~~ + +
+ +### See Also + +FillType setFillType isInverseFillType + +--- + + +## setFillType + +
+void setFillType(FillType ft)
+
+ +Sets FillType, the rule used to fill Path. While setFillType does not check +that ft is legal, values outside of FillType are not supported. + +### Parameters + + + +
ft +one of: kWinding FillType, kEvenOdd FillType, kInverseWinding FillType, +kInverseEvenOdd FillType.
+ +### Example + +
If empty Path is set to inverse FillType, it fills all pixels.
+ +### See Also + +FillType getFillType toggleInverseFillType + +--- + + +## isInverseFillType + +
+bool isInverseFillType() const
+
+ +Returns if FillType describes area outside Path geometry. The inverse fill area +extends indefinitely. + +### Return Value + +true if FillType is kInverseWinding FillType or kInverseEvenOdd FillType. + +### Example + +
+ +#### Example Output + +~~~~ +default path fill type is inverse: false +~~~~ + +
+ +### See Also + +FillType getFillType setFillType toggleInverseFillType + +--- + + +## toggleInverseFillType + +
+void toggleInverseFillType()
+
+ +Replace FillType with its inverse. The inverse of FillType describes the area +unmodified by the original FillType. + +| FillType | toggled FillType | +| --- | --- | +| kWinding FillType | kInverseWinding FillType | +| kEvenOdd FillType | kInverseEvenOdd FillType | +| kInverseWinding FillType | kWinding FillType | +| kInverseEvenOdd FillType | kEvenOdd FillType | + +### Example + +
Path drawn normally and through its inverse touches every pixel once.
+ +### See Also + +FillType getFillType setFillType isInverseFillType + +--- + +## Convexity + +## Enum SkPath::Convexity + +
+enum Convexity {
+kUnknown Convexity, 
+kConvex Convexity,
+kConcave Convexity 
+};
+ +Path is convex if it contains one Contour and Contour loops no more than +360 degrees, and Contour angles all have same Direction. Convex Path +may have better performance and require fewer resources on GPU Surface. + +Path is concave when either at least one Direction change is clockwise and +another is counterclockwise, or the sum of the changes in Direction is not 360 +degrees. + +Initially Path Convexity is kUnknown Convexity. Path Convexity is computed +if needed by destination Surface. + +### Constants + + + + + + + + + + + +
SkPath::kUnknown_Convexity Indicates Convexity has not been determined.
SkPath::kConvex_Convexity Path has one Contour made of a simple geometry without indentations.
SkPath::kConcave_Convexity Path has more than one Contour, or a geometry with indentations.
+ +### Example + +
+ +### See Also + +Contour Direction getConvexity getConvexityOrUnknown setConvexity isConvex + + + + +## getConvexity + +
+Convexity getConvexity() const
+
+ +Computes Convexity if required, and returns stored value. +Convexity is computed if stored value is kUnknown Convexity, +or if Path has been altered since Convexity was computed or set. + +### Return Value + +Computed or stored Convexity. + +### Example + +
+ +### See Also + +Convexity Contour Direction getConvexityOrUnknown setConvexity isConvex + +--- + + +## getConvexityOrUnknown + +
+Convexity getConvexityOrUnknown() const
+
+ +Returns last computed Convexity, or kUnknown Convexity if +Path has been altered since Convexity was computed or set. + +### Return Value + +Stored Convexity. + +### Example + +
Convexity is unknown unless getConvexity is called without a subsequent call +that alters the path.
+ +### See Also + +Convexity Contour Direction getConvexity setConvexity isConvex + +--- + + +## setConvexity + +
+void setConvexity(Convexity convexity)
+
+ +Stores convexity so that it is later returned by getConvexity or getConvexityOrUnknown. +convexity may differ from getConvexity, although setting an incorrect value may +cause incorrect or inefficient drawing. + +If convexity is kUnknown Convexity: getConvexity will +compute Convexity, and getConvexityOrUnknown will return kUnknown Convexity. + +If convexity is kConvex Convexity or kConcave Convexity, getConvexity +and getConvexityOrUnknown will return convexity until the path is +altered. + +### Parameters + + + +
convexity +One of kUnknown Convexity, kConvex Convexity, or kConcave Convexity.
+ +### Example + +
+ +### See Also + +Convexity Contour Direction getConvexity getConvexityOrUnknown isConvex + +--- + + +## isConvex + +
+bool isConvex() const
+
+ +Computes Convexity if required, and returns true if value is kConvex Convexity. +If setConvexity was called with kConvex Convexity or kConcave Convexity, and +the path has not been altered, Convexity is not recomputed. + +### Return Value + +true if Convexity stored or computed is kConvex Convexity. + +### Example + +
Concave shape is erroneously considered convex after a forced call to +setConvexity.
+ +### See Also + +Convexity Contour Direction getConvexity getConvexityOrUnknown setConvexity + +--- + + +## setIsConvex + +
+void setIsConvex(bool isConvex)
+
+ +Use setConvexity. + +--- + + +## isOval + +
+bool isOval(SkRect* rect, Direction* dir = nullptr, unsigned* start = nullptr) const
+
+ +Path is Oval if constructed by addCircle, addOval; and in some cases, +addRoundRect, addRRect. Path constructed with conicTo or rConicTo will not +return true though Path draws Oval. + +isOval triggers performance optimizations on some GPU Surface implementations. + +### Parameters + + + + + +
rect +storage for bounding Rect of Oval. Oval is Circle if rect width +equals rect height. Unwritten if Path is not Oval. May be nullptr.
dir +storage for Direction; kCW Direction if clockwise, kCCW Direction if +counterclockwise. Unwritten if Path is not Oval. May be nullptr.
start +storage for start of Oval: 0 for top, +1 for right, 2 for bottom, 3 for left. Unwritten if Path is not Oval. May be nullptr.
+ +### Return Value + +true if Path was constructed by method that reduces to Oval. + +### Example + +
+ +### See Also + +Oval addCircle addOval + +--- + + +## isRRect + +
+bool isRRect(SkRRect* rrect, Direction* dir = nullptr, unsigned* start = nullptr) const
+
+ +Path is Round Rect if constructed by addRoundRect, addRRect; and if construction +is not empty, not Rect, and not Oval. Path constructed with other other calls +will not return true though Path draws Round Rect. + +isRRect triggers performance optimizations on some GPU Surface implementations. + +### Parameters + + + + + +
rrect +storage for bounding Rect of Round Rect. +Unwritten if Path is not Round Rect. May be nullptr.
dir +storage for Direction; kCW Direction if clockwise, kCCW Direction if +counterclockwise. Unwritten if Path is not Round Rect. May be nullptr.
start +storage for start of Round Rect: 0 for top, +1 for right, 2 for bottom, 3 for left. Unwritten if Path is not Round Rect. May be nullptr.
+ +### Return Value + +true for Round Rect Path constructed by addRoundRect or addRRect. + +### Example + +
+ +### See Also + +Round Rect addRoundRect addRRect + +--- + + +## reset + +
+void reset()
+
+ +Sets Path to its intial state. +Removes Verb Array, Point Array, and Weights, and sets FillType to kWinding FillType. +Internal storage associated with Path is released. + +### Example + +
+ +### See Also + +rewind + +--- + + +## rewind + +
+void rewind()
+
+ +Sets Path to its intial state, preserving internal storage. +Removes Verb Array, Point Array, and Weights, and sets FillType to kWinding FillType. +Internal storage associated with Path is retained. + +Use rewind instead of reset if Path storage will be reused and performance +is critical. + +### Example + +
Although path1 retains its internal storage, it is indistinguishable from +a newly initialized path.
+ +### See Also + +reset + +--- + + +## isEmpty + +
+bool isEmpty() const
+
+ +Empty Path may have FillType but has no SkPoint, Verb, or Conic Weight. +SkPath() constructs empty Path; reset and (rewind) make Path empty. + +### Return Value + +true if the path contains no Verb array. + +### Example + +
+ +#### Example Output + +~~~~ +initial path is empty +after moveTo path is not empty +after rewind path is empty +after lineTo path is not empty +after reset path is empty +~~~~ + +
+ +### See Also + +SkPath() reset rewind + +--- + + +## isLastContourClosed + +
+bool isLastContourClosed() const
+
+ +Contour is closed if Path Verb array was last modified by close. When stroked, +closed Contour draws Paint Stroke Join instead of Paint Stroke Cap at first and last Point. + +### Return Value + +true if the last Contour ends with a kClose Verb. + +### Example + +
close has no effect if Path is empty; isLastContourClosed returns +false until Path has geometry followed by close.
+ +#### Example Output + +~~~~ +initial last contour is not closed +after close last contour is not closed +after lineTo last contour is not closed +after close last contour is closed +~~~~ + +
+ +### See Also + +close + +--- + + +## isFinite + +
+bool isFinite() const
+
+ +Finite Point array values are between negative SK ScalarMax and +positive SK ScalarMax. Any Point array value of +SK ScalarInfinity, SK ScalarNegativeInfinity, or SK ScalarNaN +cause isFinite to return false. + +### Return Value + +true if all Point values are finite. + +### Example + +
+ +#### Example Output + +~~~~ +initial path is finite +after line path is finite +after scale path is not finite +~~~~ + +
+ +### See Also + +SkScalar + +--- + + +## isVolatile + +
+bool isVolatile() const
+
+ +Returns true if the path is volatile; it will not be altered or discarded +by the caller after it is drawn. Paths by default have volatile set false, allowing +Surface to attach a cache of data which speeds repeated drawing. If true, Surface +may not speed repeated drawing. + +### Return Value + +true if caller will alter Path after drawing. + +### Example + +
+ +#### Example Output + +~~~~ +volatile by default is false +~~~~ + +
+ +### See Also + +setIsVolatile + +--- + + +## setIsVolatile + +
+void setIsVolatile(bool isVolatile)
+
+ +Specify whether Path is volatile; whether it will be altered or discarded +by the caller after it is drawn. Paths by default have volatile set false, allowing +Device to attach a cache of data which speeds repeated drawing. + +Mark temporary paths, discarded or modified after use, as volatile +to inform Device that the path need not be cached. + +Mark animating Path volatile to improve performance. +Mark unchanging Path non-volative to improve repeated rendering. + +Raster Surface Path draws are affected by volatile for some shadows. +GPU Surface Path draws are affected by volatile for some shadows and concave geometries. + +### Parameters + + + +
isVolatile +true if caller will alter Path after drawing.
+ +### Example + +
+ +### See Also + +isVolatile + +--- + + +## IsLineDegenerate + +
+static bool IsLineDegenerate(const SkPoint& p1, const SkPoint& p2, bool exact)
+
+ +Test if Line between Point pair is degenerate. +Line with no length or that moves a very short distance is degenerate; it is +treated as a point. + +### Parameters + + + + + +
p1 +Line start point.
p2 +Line end point.
exact +If true, returns true only if p1 equals p2. If false, returns true +if p1 equals or nearly equals p2.
+ +### Return Value + +true if Line is degenerate; its length is effectively zero. + +### Example + +
As single precision floats, 100 and 100.000001f have the same bit representation, +and are exactly equal. 100 and 100.0001f have different bit representations, and +are not exactly equal, but are nearly equal.
+ +#### Example Output + +~~~~ +line from (100,100) to (100,100) is degenerate, nearly +line from (100,100) to (100,100) is degenerate, exactly +line from (100,100) to (100.0001,100.0001) is degenerate, nearly +line from (100,100) to (100.0001,100.0001) is not degenerate, exactly +~~~~ + +
+ +### See Also + +IsQuadDegenerate IsCubicDegenerate SkPoint::equalsWithinTolerance + +--- + + +## IsQuadDegenerate + +
+static bool IsQuadDegenerate(const SkPoint& p1, const SkPoint& p2,
+                             const SkPoint& p3, bool exact)
+
+ +Test if Quad is degenerate. +Quad with no length or that moves a very short distance is degenerate; it is +treated as a point. + +### Parameters + + + + + + +
p1 +Quad start point.
p2 +Quad control point.
p3 +Quad end point.
exact +If true, returns true only if p1, p2, and p3 are equal. +If false, returns true if p1, p2, and p3 are equal or nearly equal.
+ +### Return Value + +true if Quad is degenerate; its length is effectively zero. + +### Example + +
As single precision floats: 100, 100.00001f, and 100.00002f have different bit representations +but nearly the same value. Translating all three by 1000 gives them the same bit representation; +the fractional portion of the number can't be represented by the float and is lost.
+ +#### Example Output + +~~~~ +quad (100,100), (100.00001,100.00001), (100.00002,100.00002) is degenerate, nearly +quad (1100,1100), (1100,1100), (1100,1100) is degenerate, nearly +quad (100,100), (100.00001,100.00001), (100.00002,100.00002) is not degenerate, exactly +quad (1100,1100), (1100,1100), (1100,1100) is degenerate, exactly +~~~~ + +
+ +### See Also + +IsLineDegenerate IsCubicDegenerate SkPoint::equalsWithinTolerance + +--- + + +## IsCubicDegenerate + +
+static bool IsCubicDegenerate(const SkPoint& p1, const SkPoint& p2,
+                              const SkPoint& p3, const SkPoint& p4, bool exact)
+
+ +Test if Cubic is degenerate. +Cubic with no length or that moves a very short distance is degenerate; it is +treated as a point. + +### Parameters + + + + + + + +
p1 +Cubic start point.
p2 +Cubic control point 1.
p3 +Cubic control point 2.
p4 +Cubic end point.
exact +If true, returns true only if p1, p2, p3, and p4 are equal. +If false, returns true if p1, p2, p3, and p4 are equal or nearly equal.
+ +### Return Value + +true if Cubic is degenerate; its length is effectively zero. + +### Example + +
+ +#### Example Output + +~~~~ +0.00024414062 is degenerate +0.00024414065 is length +~~~~ + +
+ +--- + + +## isLine + +
+bool isLine(SkPoint line[2]) const
+
+ +Returns true if Path contains only one Line; +Path Verb array has two entries: kMove Verb, kLine Verb. +If Path contains one Line and line is not nullptr, line is set to +Line start point and Line end point. +Returns false if Path is not one Line; line is unaltered. + +### Parameters + + + +
line +storage for Line. May be nullptr.
+ +### Return Value + +true if Path contains exactly one Line. + +### Example + +
+ +#### Example Output + +~~~~ +empty is not line +zero line is line (0,0) (0,0) +line is line (10,10) (20,20) +second move is not line +~~~~ + +
+ +--- + +## Point Array + +Point Array contains Points satisfying the allocated Points for +each Verb in Verb Array. For instance, Path containing one Contour with Line +and Quad is described by Verb Array: move to, line to, quad to; and +one Point for move, one Point for Line, two Points for Quad; totaling four Points. + +Point Array may be read directly from Path with getPoints, or inspected with +getPoint, with Iter, or with RawIter. + + +## getPoints + +
+int getPoints(SkPoint points[], int max) const
+
+ +Returns number of points in Path. Up to max points are copied. +points may be nullptr; then, max must be zero. +If max is greater than number of points, excess points storage is unaltered. + +### Parameters + + + + +
points +storage for Path Point array. May be nullptr.
max +Number of points alloted in points storage; must be greater than or equal to zero.
+ +### Return Value + +Path Point array length. + +### Example + +
+ +#### Example Output + +~~~~ +no points point count: 3 +zero max point count: 3 +too small point count: 3 (0,0) (20,20) +just right point count: 3 (0,0) (20,20) (-10,-10) +~~~~ + +
+ +### See Also + +countPoints getPoint + +--- + + +## countPoints + +
+int countPoints() const
+
+ +Returns the number of points in Path. +Point count is initially zero. + +### Return Value + +Path Point array length. + +### Example + +
+ +#### Example Output + +~~~~ +empty point count: 0 +zero line point count: 2 +line point count: 2 +second move point count: 3 +~~~~ + +
+ +### See Also + +getPoints + +--- + + +## getPoint + +
+SkPoint getPoint(int index) const
+
+ +Returns Point at index in Point Array. Valid range for index is +0 to countPoints - 1. +If the index is out of range, getPoint returns (0, 0). + +### Parameters + + + +
index +Point Array element selector.
+ +### Return Value + +Point Array value or (0, 0). + +### Example + +
+ +#### Example Output + +~~~~ +point 0: (-10,-10) +point 1: (10,10) +~~~~ + +
+ +### See Also + +countPoints getPoints + +--- + +## Verb Array + +Verb Array always starts with kMove Verb. +If kClose Verb is not the last entry, it is always followed by kMove Verb; +the quantity of kMove Verb equals the Contour count. +Verb Array does not include or count kDone Verb; it is a convenience +returned when iterating through Verb Array. + +Verb Array may be read directly from Path with getVerbs, or inspected with Iter, +or with RawIter. + + +## countVerbs + +
+int countVerbs() const
+
+ +Returns the number of Verbs: kMove Verb, kLine Verb, kQuad Verb, kConic Verb, +kCubic Verb, and kClose Verb; added to Path. + +### Return Value + +Length of Verb Array. + +### Example + +
+ +#### Example Output + +~~~~ +empty verb count: 0 +round rect verb count: 10 +~~~~ + +
+ +### See Also + +getVerbs Iter RawIter + +--- + + +## getVerbs + +
+int getVerbs(uint8_t verbs[], int max) const
+
+ +Returns the number of verbs in the path. Up to max verbs are copied. The +verbs are copied as one byte per verb. + +### Parameters + + + + +
verbs +If not null, receives up to max verbs
max +The maximum number of verbs to copy into verbs
+ +### Return Value + +the actual number of verbs in the path + +### Example + +
+ +#### Example Output + +~~~~ +no verbs verb count: 3 +zero max verb count: 3 +too small verb count: 3 move line +just right verb count: 3 move line line +~~~~ + +
+ +### See Also + +countVerbs getPoints Iter RawIter + +--- + + +## swap + +
+void swap(SkPath& other)
+
+ +Exchanges the Verb Array, Point Array, Weights, and Fill Type with other. +Cached state is also exchanged. swap internally exchanges pointers, so +it is lightweight and does not allocate memory. + +swap usage has largely been replaced by operator=(const SkPath& path). +Paths do not copy their content on assignment util they are written to, +making assignment as efficient as swap. + +### Parameters + + + +
other +Path exchanged by value.
+ +### Example + +
+ +#### Example Output + +~~~~ +path1 bounds = 0, 0, 0, 0 +path2 bounds = 10, 20, 30, 40 +~~~~ + +
+ +### See Also + +operator=(const SkPath& path) + +--- + + +## getBounds + +
+const SkRect& getBounds() const
+
+ +Returns minimum and maximum x and y values of Point Array. If Path contains +no points, getBounds returns (0, 0, 0, 0). Returned bounds width and height may +be larger or smaller than area affected when Path is drawn. + +getBounds includes all Points added to Path, including Points associated with +kMove Verb that define empty Contours. + +### Return Value + +bounds of all Points in Point Array. + +### Example + +
Bounds of upright Circle can be predicted from center and radius. +Bounds of rotated Circle includes control Points outside of filled area.
+ +#### Example Output + +~~~~ +empty bounds = 0, 0, 0, 0 +circle bounds = 25, 20, 75, 70 +rotated circle bounds = 14.6447, 9.64466, 85.3553, 80.3553 +~~~~ + +
+ +### See Also + +computeTightBounds updateBoundsCache + +--- + + +## updateBoundsCache + +
+void updateBoundsCache() const
+
+ +Update internal bounds so that subsequent calls to getBounds are instantaneous. +Unaltered copies of Path may also access cached bounds through getBounds. + +For now, updateBoundsCache is identical to getBounds, where the +returned value is ignored. + +updateBoundsCache prepares a Path subsequently drawn from multiple threads, +to avoid a race condition where each draw separately computes the bounds. + +### Example + +
+ +#### Example Output + +~~~~ +#Volatile +uncached avg: 0.18048 ms +cached avg: 0.182784 ms +~~~~ + +
+ +### See Also + +getBounds + +--- + + +## computeTightBounds + +
+SkRect computeTightBounds() const
+
+ +Returns minimum and maximum x and y values of the lines and curves in Path. +If Path contains no points, computeTightBounds returns (0, 0, 0, 0). +Returned bounds width and height may be larger or smaller than area affected +when Path is drawn. + +computeTightBounds behaves identically to getBounds when Path contains +only lines. If Path contains curves, compute computeTightBounds includes +the maximum extent of the Quad, Conic, or Cubic; is slower, +and does not cache the result. + +Like getBounds, computeTightBounds includes Points associated with +kMove Verb that define empty Contours. + +### Return Value + +### Example + +
+ +#### Example Output + +~~~~ +empty bounds = 0, 0, 0, 0 +circle bounds = 25, 20, 75, 70 +rotated circle bounds = 25, 20, 75, 70 +~~~~ + +
+ +### See Also + +getBounds + +--- + + +## conservativelyContainsRect + +
+bool conservativelyContainsRect(const SkRect& rect) const
+
+ +Returns true if rect is contained by Path. +May return false when rect is contained by Path. + +For now, only returns true if Path has one Contour and is convex. +rect may share points and edges with Path and be contained. +If rect is empty, that is, it has zero width or height; conservativelyContainsRect +returns true if the Point or Line described by rect is contained by Path. + +### Parameters + + + +
rect +Rect, Line, or Point checked for containment.
+ +### Return Value + +true if rect is contained. + +### Example + +
Rect is drawn in blue if it is contained by red Path.
+ +### See Also + +contains Op Rect Convexity + +--- + + +## incReserve + +
+void incReserve(unsigned extraPtCount)
+
+ +grows Path Verb Array and Point Array to contain extraPtCount additional Points. +incReserve may improve performance and use less memory by +reducing the number and size of allocations when creating Path. + +### Parameters + + + +
extraPtCount +number of additional Points to preallocate.
+ +### Example + +
+ +### See Also + +Point Array + +--- + + +## moveTo + +
+void moveTo(SkScalar x, SkScalar y)
+
+ +Adds beginning of Contour at Point (x, y). + +### Parameters + + + + +
x +x-coordinate of Contour start.
y +y-coordinate of Contour start.
+ +### Example + +
+ +### See Also + +Contour lineTo rMoveTo quadTo conicTo cubicTo close + +--- + +
+void moveTo(const SkPoint& p)
+
+ +Adds beginning of Contour at Point p. + +### Parameters + + + +
p +Contour start.
+ +### Example + +
+ +### See Also + +Contour lineTo rMoveTo quadTo conicTo cubicTo close + +--- + + +## rMoveTo + +
+void rMoveTo(SkScalar dx, SkScalar dy)
+
+ +Adds beginning of Contour relative to Last Point. +If Path is empty, starts Contour at (dx, dy). +Otherwise, start Contour at Last Point offset by (dx, dy). +rMoveTo stands for relative move to. + +### Parameters + + + + +
dx +offset from Last Point x to Contour start x.
dy +offset from Last Point y to Contour start y.
+ +### Example + +
+ +### See Also + +Contour lineTo moveTo quadTo conicTo cubicTo close + +--- + + +## lineTo + +
+void lineTo(SkScalar x, SkScalar y)
+
+ +Adds Line from Last Point to (x, y). If Path is empty, or last Verb is +kClose Verb, Last Point is set to (0, 0) before adding Line. + +lineTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +lineTo then appends kLine Verb to Verb Array and (x, y) to Point Array. + +### Parameters + + + + +
x +end of added Line in x.
y +end of added Line in y.
+ +### Example + +
+ +### See Also + +Contour moveTo rLineTo addRect + +--- + +
+void lineTo(const SkPoint& p)
+
+ +Adds Line from Last Point to Point p. If Path is empty, or last Verb is +kClose Verb, Last Point is set to (0, 0) before adding Line. + +lineTo first appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +lineTo then appends kLine Verb to Verb Array and Point p to Point Array. + +### Parameters + + + +
p +end Point of added Line.
+ +### Example + +
+ +### See Also + +Contour moveTo rLineTo addRect + +--- + + +## rLineTo + +
+void rLineTo(SkScalar dx, SkScalar dy)
+
+ +Adds Line from Last Point to Vector (dx, dy). If Path is empty, or last Verb is +kClose Verb, Last Point is set to (0, 0) before adding Line. + +rLineTo first appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +rLineTo then appends kLine Verb to Verb Array and Line end to Point Array. +Line end is Last Point plus Vector (dx, dy). +rLineTo stands for relative line to. + +### Parameters + + + + +
dx +offset from Last Point x to Line end x.
dy +offset from Last Point y to Line end y.
+ +### Example + +
+ +### See Also + +Contour moveTo lineTo addRect + +--- + +# Quad +Quad describes a quadratic Bezier, a second-order curve identical to a section +of a parabola. Quad begins at a start Point, curves towards a control Point, +and then curves to an end Point. + +### Example + +
+ +Quad is a special case of Conic where Conic Weight is set to one. + +Quad is always contained by the triangle connecting its three Points. Quad +begins tangent to the line between start Point and control Point, and ends +tangent to the line between control Point and end Point. + +### Example + +
+ + +## quadTo + +
+void quadTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2)
+
+ +Adds Quad from Last Point towards (x1, y1), to (x2, y2). +If Path is empty, or last Verb is kClose Verb, Last Point is set to (0, 0) +before adding Quad. + +quadTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +quadTo then appends kQuad Verb to Verb Array; and (x1, y1), (x2, y2) +to Point Array. + +### Parameters + + + + + + +
x1 +control Point of Quad in x.
y1 +control Point of Quad in y.
x2 +end Point of Quad in x.
y2 +end Point of Quad in y.
+ +### Example + +
+ +### See Also + +Contour moveTo conicTo rQuadTo + +--- + +
+void quadTo(const SkPoint& p1, const SkPoint& p2)
+
+ +Adds Quad from Last Point towards Point p1, to Point p2. +If Path is empty, or last Verb is kClose Verb, Last Point is set to (0, 0) +before adding Quad. + +quadTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +quadTo then appends kQuad Verb to Verb Array; and Points p1, p2 +to Point Array. + +### Parameters + + + + +
p1 +control Point of added Quad.
p2 +end Point of added Quad.
+ +### Example + +
+ +### See Also + +Contour moveTo conicTo rQuadTo + +--- + + +## rQuadTo + +
+void rQuadTo(SkScalar dx1, SkScalar dy1, SkScalar dx2, SkScalar dy2)
+
+ +Adds Quad from Last Point towards Vector (dx1, dy1), to Vector (dx2, dy2). +If Path is empty, or last Verb +is kClose Verb, Last Point is set to (0, 0) before adding Quad. + +rQuadTo first appends kMove Verb to Verb Array and (0, 0) to Point Array, +if needed. rQuadTo then appends kQuad Verb to Verb Array; and appends Quad +control and Quad end to Point Array. +Quad control is Last Point plus Vector (dx1, dy1). +Quad end is Last Point plus Vector (dx2, dy2). +rQuadTo stands for relative quad to. + +### Parameters + + + + + + +
dx1 +offset from Last Point x to Quad control x.
dy1 +offset from Last Point x to Quad control y.
dx2 +offset from Last Point x to Quad end x.
dy2 +offset from Last Point x to Quad end y.
+ +### Example + +
+ +### See Also + +Contour moveTo conicTo quadTo + +--- + +# Conic +Conic describes a conical section: a piece of an ellipse, or a piece of a +parabola, or a piece of a hyperbola. Conic begins at a start Point, +curves towards a control Point, and then curves to an end Point. The influence +of the control Point is determined by Conic Weight. + +Each Conic in Path adds two Points and one Weight. Weights in Path may be +inspected with Iter, or with RawIter. + +## Weight + +Weight determines both the strength of the control Point and the type of Conic. +If Weight is exactly one, then Conic is identical to Quad; it is always a +parabolic segment. + +### Example + +
When Conic weight is one, Quad is added to path; the two are identical.
+ +#### Example Output + +~~~~ +move {0, 0}, +quad {0, 0}, {20, 30}, {50, 60}, +done +~~~~ + +
+ +If weight is less than one, Conic is an elliptical segment. + +### Example + +
A 90 degree circular arc has the weight1 / sqrt(2).
+ +#### Example Output + +~~~~ +move {0, 0}, +conic {0, 0}, {20, 0}, {20, 20}, weight = 0.707107 +done +~~~~ + +
+ +If weight is greater than one, Conic is a hyperbolic segment. As w gets large, +a hyperbolic segment can be approximated by straight lines connecting the +control Point with the end Points. + +### Example + +
+ +#### Example Output + +~~~~ +move {0, 0}, +line {0, 0}, {20, 0}, +line {20, 0}, {20, 20}, +done +~~~~ + +
+ + +## conicTo + +
+void conicTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar w)
+
+ +Adds Conic from Last Point towards (x1, y1), to (x2, y2), weighted by w. +If Path is empty, or last Verb is kClose Verb, Last Point is set to (0, 0) +before adding Conic. + +conicTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. + +If w is finite and not one, conicTo then appends kConic Verb to Verb Array; +and (x1, y1), (x2, y2) to Point Array; and w to Weights. + +If w is one, conicTo appends kQuad Verb to Verb Array, and +(x1, y1), (x2, y2) to Point Array. + +If w is not finite, conicTo appends kLine Verb twice to Verb Array, and +(x1, y1), (x2, y2) to Point Array. + +### Parameters + + + + + + + +
x1 +control Point of Conic in x.
y1 +control Point of Conic in y.
x2 +end Point of Conic in x.
y2 +end Point of Conic in y.
w +weight of added Conic.
+ +### Example + +
As weight increases, curve is pulled towards control point. +The bottom two curves are elliptical; the next is parabolic; the +top curve is hyperbolic.
+ +### See Also + +rConicTo arcTo addArc quadTo + +--- + +
+void conicTo(const SkPoint& p1, const SkPoint& p2, SkScalar w)
+
+ +Adds Conic from Last Point towards Point p1, to Point p2, weighted by w. +If Path is empty, or last Verb is kClose Verb, Last Point is set to (0, 0) +before adding Conic. + +conicTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. + +If w is finite and not one, conicTo then appends kConic Verb to Verb Array; +and Points p1, p2 to Point Array; and w to Weights. + +If w is one, conicTo appends kQuad Verb to Verb Array, and Points p1, p2 +to Point Array. + +If w is not finite, conicTo appends kLine Verb twice to Verb Array, and +Points p1, p2 to Point Array. + +### Parameters + + + + + +
p1 +control Point of added Conic.
p2 +end Point of added Conic.
w +weight of added Conic.
+ +### Example + +
Conics and arcs use identical representations. As the arc sweep increases +the conic weight also increases, but remains smaller than one.
+ +### See Also + +rConicTo arcTo addArc quadTo + +--- + + +## rConicTo + +
+void rConicTo(SkScalar dx1, SkScalar dy1, SkScalar dx2, SkScalar dy2, SkScalar w)
+
+ +Adds Conic from Last Point towards Vector (dx1, dy1), to Vector (dx2, dy2), +weighted by w. If Path is empty, or last Verb +is kClose Verb, Last Point is set to (0, 0) before adding Conic. + +rConicTo first appends kMove Verb to Verb Array and (0, 0) to Point Array, +if needed. +If w is finite and not one, rConicTo then appends kConic Verb to Verb Array, +and w is recorded as Conic Weight; otherwise, if w is one, rConicTo appends +kQuad Verb to Verb Array; or if w is not finite, rConicTo appends kLine Verb +twice to Verb Array. + +In all cases rConicTo then appends Points control and end to Point Array. +control is Last Point plus Vector (dx1, dy1). +end is Last Point plus Vector (dx2, dy2). + +rConicTo stands for relative conic to. + +### Parameters + + + + + + + +
dx1 +offset from Last Point x to Conic control x.
dy1 +offset from Last Point x to Conic control y.
dx2 +offset from Last Point x to Conic end x.
dy2 +offset from Last Point x to Conic end y.
w +weight of added Conic.
+ +### Example + +
+ +### See Also + +conicTo arcTo addArc quadTo + +--- + +# Cubic +Cubic describes a cubic Bezier, a third-order curve. +Cubic begins at a start Point, curving towards the first control Point; +and curves from the end Point towards the second control Point. + +### Example + +
+ + +## cubicTo + +
+void cubicTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar x3,
+             SkScalar y3)
+
+ +Adds Cubic from Last Point towards (x1, y1), then towards (x2, y2), ending at +(x3, y3). If Path is empty, or last Verb is kClose Verb, Last Point is set to +(0, 0) before adding Cubic. + +cubicTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +cubicTo then appends kCubic Verb to Verb Array; and (x1, y1), (x2, y2), (x3, y3) +to Point Array. + +### Parameters + + + + + + + + +
x1 +first control Point of Cubic in x.
y1 +first control Point of Cubic in y.
x2 +second control Point of Cubic in x.
y2 +second control Point of Cubic in y.
x3 +end Point of Cubic in x.
y3 +end Point of Cubic in y.
+ +### Example + +
+ +### See Also + +Contour moveTo rCubicTo quadTo + +--- + +
+void cubicTo(const SkPoint& p1, const SkPoint& p2, const SkPoint& p3)
+
+ +Adds Cubic from Last Point towards Point p1, then towards Point p2, ending at +Point p3. If Path is empty, or last Verb is kClose Verb, Last Point is set to +(0, 0) before adding Cubic. + +cubicTo appends kMove Verb to Verb Array and (0, 0) to Point Array, if needed. +cubicTo then appends kCubic Verb to Verb Array; and Points p1, p2, p3 +to Point Array. + +### Parameters + + + + + +
p1 +first control Point of Cubic.
p2 +second control Point of Cubic.
p3 +end Point of Cubic.
+ +### Example + +
+ +### See Also + +Contour moveTo rCubicTo quadTo + +--- + + +## rCubicTo + +
+void rCubicTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar x3,
+              SkScalar y3)
+
+ +Adds Cubic from Last Point towards Vector (dx1, dy1), then towards +Vector (dx2, dy2), to Vector (dx3, dy3). +If Path is empty, or last Verb +is kClose Verb, Last Point is set to (0, 0) before adding Cubic. + +rCubicTo first appends kMove Verb to Verb Array and (0, 0) to Point Array, +if needed. rCubicTo then appends kCubic Verb to Verb Array; and appends Cubic +control and Cubic end to Point Array. +Cubic control is Last Point plus Vector (dx1, dy1). +Cubic end is Last Point plus Vector (dx2, dy2). +rCubicTo stands for relative cubic to. + +### Parameters + + + + + + + + +
x1 +offset from Last Point x to first Cubic control x.
y1 +offset from Last Point x to first Cubic control y.
x2 +offset from Last Point x to second Cubic control x.
y2 +offset from Last Point x to second Cubic control y.
x3 +offset from Last Point x to Cubic end x.
y3 +offset from Last Point x to Cubic end y.
+ +### Example + +
+ +### See Also + +Contour moveTo cubicTo quadTo + +--- + +# Arc +Arc can be constructed in a number of ways. Arc may be described by part of Oval and angles, +by start point and end point, and by radius and tangent lines. Each construction has advantages, +and some constructions correspond to Arc drawing in graphics standards. + +All Arc draws are implemented by one or more Conic draws. When Conic Weight is less than one, +Conic describes an Arc of some Oval or Circle. + +arcTo(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle, bool forceMoveTo) +describes Arc as a piece of Oval, beginning at start angle, sweeping clockwise or counterclockwise, +which may continue Contour or start a new one. This construction is similar to PostScript and +HTML Canvas arcs. Variation addArc always starts new Contour. Canvas::drawArc draws without +requiring Path. + +arcTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar radius) +describes Arc as tangent to the line (x0, y0), (x1, y1) and tangent to the line (x1, y1), (x2, y2) +where (x0, y0) is the last Point added to Path. This construction is similar to PostScript and +HTML Canvas arcs. + +arcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc, Direction sweep, +SkScalar x, SkScalar y) +describes Arc as part of Oval with radii (rx, ry), beginning at +last Point added to Path and ending at (x, y). More than one Arc satisfies this criteria, +so additional values choose a single solution. This construction is similar to SVG arcs. + +conicTo describes Arc of less than 180 degrees as a pair of tangent lines and Conic Weight. +conicTo can represent any Arc with a sweep less than 180 degrees at any rotation. All arcTo +constructions are converted to Conic data when added to Path. + +### Example + +
+ +### Example + +
1 describes an arc from an oval, a starting angle, and a sweep angle. +2 is similar to 1, but does not require building a path to draw. +3 is similar to 1, but always begins new Contour. +4 describes an arc from a pair of tangent lines and a radius. +5 describes an arc from Oval center, arc start Point and arc end Point. +6 describes an arc from a pair of tangent lines and a Conic Weight.
+ + +## arcTo + +
+void arcTo(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle,
+           bool forceMoveTo)
+
+ +Append Arc to Path. Arc added is part of ellipse +bounded by oval, from startAngle through sweepAngle. Both startAngle and +sweepAngle are measured in degrees, where zero degrees is aligned with the +positive x-axis, and positive sweeps extends Arc clockwise. + +arcTo adds Line connecting Path last Point to initial Arc Point if forceMoveTo +is false and Path is not empty. Otherwise, added Contour begins with first point +of Arc. Angles greater than -360 and less than 360 are treated modulo 360. + +### Parameters + + + + + + +
oval +bounds of ellipse containing Arc.
startAngle +starting angle of Arc in degrees.
sweepAngle +sweep, in degrees. Positive is clockwise; treated modulo 360.
forceMoveTo +true to start a new contour with Arc.
+ +### Example + +
arcTo continues a previous contour when forceMoveTo is false and when Path +is not empty.
+ +### See Also + +addArc SkCanvas::drawArc conicTo + +--- + +
+void arcTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar radius)
+
+ +Append Arc to Path, after appending Line if needed. Arc is implemented by Conic +weighted to describe part of Circle. Arc is contained by tangent from +last Path point (x0, y0) to (x1, y1), and tangent from (x1, y1) to (x2, y2). Arc +is part of Circle sized to radius, positioned so it touches both tangent lines. + +### Example + +
+ +If last Path Point does not start Arc, arcTo appends connecting Line to Path. +The length of Vector from (x1, y1) to (x2, y2) does not affect Arc. + +### Example + +
+ +Arc sweep is always less than 180 degrees. If radius is zero, or if +tangents are nearly parallel, arcTo appends Line from last Path Point to (x1, y1). + +arcTo appends at most one Line and one Conic. +arcTo implements the functionality of PostScript arct and HTML Canvas arcTo. + +### Parameters + + + + + + + +
x1 +x common to pair of tangents.
y1 +y common to pair of tangents.
x2 +x end of second tangent.
y2 +y end of second tangent.
radius +distance from Arc to Circle center.
+ +### Example + +
arcTo is represented by Line and circular Conic in Path.
+ +#### Example Output + +~~~~ +move to (156,20) +line (156,20),(79.2893,20) +conic (79.2893,20),(200,20),(114.645,105.355) weight 0.382683 +~~~~ + +
+ +### See Also + +conicTo + +--- + +
+void arcTo(const SkPoint p1, const SkPoint p2, SkScalar radius)
+
+ +Append Arc to Path, after appending Line if needed. Arc is implemented by Conic +weighted to describe part of Circle. Arc is contained by tangent from +last Path point to p1, and tangent from p1 to p2. Arc +is part of Circle sized to radius, positioned so it touches both tangent lines. + +If last Path Point does not start Arc, arcTo appends connecting Line to Path. +The length of Vector from p1 to p2 does not affect Arc. + +Arc sweep is always less than 180 degrees. If radius is zero, or if +tangents are nearly parallel, arcTo appends Line from last Path Point to p1. + +arcTo appends at most one Line and one Conic. +arcTo implements the functionality of PostScript arct and HTML Canvas arcTo. + +### Parameters + + + + + +
p1 +Point common to pair of tangents.
p2 +end of second tangent.
radius +distance from Arc to Circle center.
+ +### Example + +
Because tangent lines are parallel, arcTo appends line from last Path Point to +p1, but does not append a circular Conic.
+ +#### Example Output + +~~~~ +move to (156,20) +line (156,20),(200,20) +~~~~ + +
+ +### See Also + +conicTo + +--- + +## Enum SkPath::ArcSize + +
+enum ArcSize {
+kSmall ArcSize 
+kLarge ArcSize 
+};
+ +Four Oval parts with radii (rx, ry) start at last Path Point and ends at (x, y). +ArcSize and Direction select one of the four Oval parts. + +### Constants + + + + + + + + +
SkPath::kSmall_ArcSize 0Smaller of Arc pair.
SkPath::kLarge_ArcSize 1Larger of Arc pair.
+ +### Example + +
Arc begins at top of Oval pair and ends at bottom. Arc can take four routes to get there. +Two routes are large, and two routes are counterclockwise. The one route both large +and counterclockwise is blue.
+ +### See Also + +arcTo Direction + +
+void arcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc,
+           Direction sweep, SkScalar x, SkScalar y)
+
+ +Append Arc to Path. Arc is implemented by one or more Conic weighted to describe part of Oval +with radii (rx, ry) rotated by xAxisRotate degrees. Arc curves from last Path Point to (x, y), +choosing one of four possible routes: clockwise or counterclockwise, and smaller or larger. + +Arc sweep is always less than 360 degrees. arcTo appends Line to (x, y) if either radii are zero, +or if last Path Point equals (x, y). arcTo scales radii (rx, ry) to fit last Path Point and +(x, y) if both are greater than zero but too small. + +arcTo appends up to four Conic curves. +arcTo implements the functionatlity of SVG Arc, although SVG sweep-flag value is +opposite the integer value of sweep; SVG sweep-flag uses 1 for clockwise, while kCW Direction +cast to int is zero. + +### Parameters + + + + + + + + + +
rx +radius in x before x-axis rotation.
ry +radius in y before x-axis rotation.
xAxisRotate +x-axis rotation in degrees; positve values are clockwise.
largeArc +chooses smaller or larger Arc.
sweep +chooses clockwise or counterclockwise Arc.
x +end of Arc.
y +end of Arc.
+ +### Example + +
+ +### See Also + +rArcTo ArcSize Direction + +--- + +
+void arcTo(const SkPoint r, SkScalar xAxisRotate, ArcSize largeArc,
+           Direction sweep, const SkPoint xy)
+
+ +Append Arc to Path. Arc is implemented by one or more Conic weighted to describe part of Oval +with radii (r.fX, r.fY) rotated by xAxisRotate degrees. Arc curves from last Path Point to +(xy.fX, xy.fY), choosing one of four possible routes: clockwise or counterclockwise, +and smaller or larger. + +Arc sweep is always less than 360 degrees. arcTo appends Line to xy if either radii are zero, +or if last Path Point equals (x, y). arcTo scales radii r to fit last Path Point and +xy if both are greater than zero but too small. + +arcTo appends up to four Conic curves. +arcTo implements the functionatlity of SVG Arc, although SVG sweep-flag value is +opposite the integer value of sweep; SVG sweep-flag uses 1 for clockwise, while kCW Direction +cast to int is zero. + +### Parameters + + + + + + + +
r +radii in x and y before x-axis rotation.
xAxisRotate +x-axis rotation in degrees; positve values are clockwise.
largeArc +chooses smaller or larger Arc.
sweep +chooses clockwise or counterclockwise Arc.
xy +end of Arc.
+ +### Example + +
+ +### See Also + +rArcTo ArcSize Direction + +--- + + +## rArcTo + +
+void rArcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc,
+            Direction sweep, SkScalar dx, SkScalar dy)
+
+ +Append Arc to Path, relative to last Path Point. Arc is implemented by one or +more Conic, weighted to describe part of Oval with radii (r.fX, r.fY) rotated by +xAxisRotate degrees. Arc curves from last Path Point (x0, y0) to +(x0 + dx, y0 + dy), choosing one of four possible routes: clockwise or +counterclockwise, and smaller or larger. If Path is empty, the start Arc Point +is (0, 0). + +Arc sweep is always less than 360 degrees. arcTo appends Line to xy if either +radii are zero, or if last Path Point equals (x, y). arcTo scales radii r to fit +last Path Point and xy if both are greater than zero but too small. + +arcTo appends up to four Conic curves. +arcTo implements the functionatlity of SVG Arc, although SVG sweep-flag value is +opposite the integer value of sweep; SVG sweep-flag uses 1 for clockwise, while +kCW Direction cast to int is zero. + +### Parameters + + + + + + + + + +
rx +radius in x before x-axis rotation.
ry +radius in y before x-axis rotation.
xAxisRotate +x-axis rotation in degrees; positve values are clockwise.
largeArc +chooses smaller or larger Arc.
sweep +chooses clockwise or counterclockwise Arc.
dx +x offset end of Arc from last Path Point.
dy +y offset end of Arc from last Path Point.
+ +### Example + +
+ +### See Also + +arcTo ArcSize Direction + +--- + + +## close + +
+void close()
+
+ +Append kClose Verb to Path. A closed Contour connects the first and last Point +with Line, forming a continous loop. Open and closed Contour draw the same +with SkPaint::kFill Style. With SkPaint::kStroke Style, open Contour draws +Paint Stroke Cap at Contour start and end; closed Contour draws +Paint Stroke Join at Contour start and end. + +close has no effect if Path is empty or last Path Verb is kClose Verb. + +### Example + +
+ +### See Also + +--- + + +## IsInverseFillType + +
+static bool IsInverseFillType(FillType fill)
+
+ +Returns true if fill is inverted and Path with fill represents area outside +of its geometric bounds. + +| FillType | is inverse | +| --- | --- | +| kWinding FillType | false | +| kEvenOdd FillType | false | +| kInverseWinding FillType | true | +| kInverseEvenOdd FillType | true | + +### Parameters + + + +
fill +one of: kWinding FillType, kEvenOdd FillType, +kInverseWinding FillType, kInverseEvenOdd FillType.
+ +### Return Value + +true if Path fills outside its bounds. + +### Example + +
+ +#### Example Output + +~~~~ +IsInverseFillType(kWinding_FillType) == false +IsInverseFillType(kEvenOdd_FillType) == false +IsInverseFillType(kInverseWinding_FillType) == true +IsInverseFillType(kInverseEvenOdd_FillType) == true +~~~~ + +
+ +### See Also + +FillType getFillType setFillType ConvertToNonInverseFillType + +--- + + +## ConvertToNonInverseFillType + +
+static FillType ConvertToNonInverseFillType(FillType fill)
+
+ +Returns equivalent Fill Type representing Path fill inside its bounds. +. + +| FillType | inside FillType | +| --- | --- | +| kWinding FillType | kWinding FillType | +| kEvenOdd FillType | kEvenOdd FillType | +| kInverseWinding FillType | kWinding FillType | +| kInverseEvenOdd FillType | kEvenOdd FillType | + +### Parameters + + + +
fill +one of: kWinding FillType, kEvenOdd FillType, +kInverseWinding FillType, kInverseEvenOdd FillType.
+ +### Return Value + +fill, or kWinding FillType or kEvenOdd FillType if fill is inverted. + +### Example + +
+ +#### Example Output + +~~~~ +ConvertToNonInverseFillType(kWinding_FillType) == kWinding_FillType +ConvertToNonInverseFillType(kEvenOdd_FillType) == kEvenOdd_FillType +ConvertToNonInverseFillType(kInverseWinding_FillType) == kWinding_FillType +ConvertToNonInverseFillType(kInverseEvenOdd_FillType) == kEvenOdd_FillType +~~~~ + +
+ +### See Also + +FillType getFillType setFillType IsInverseFillType + +--- + + +## ConvertConicToQuads + +
+static int ConvertConicToQuads(const SkPoint& p0, const SkPoint& p1,
+                               const SkPoint& p2, SkScalar w, SkPoint pts[],
+                               int pow2)
+
+ +Approximates Conic with Quad array. Conic is constructed from start Point p0, +control Point p1, end Point p2, and weight w. +Quad array is stored in pts; this storage is supplied by caller. +Maximum Quad count is 2 to the pow2. +Every third point in array shares last Point of previous Quad and first Point of +next Quad. Maximum pts storage size is given by: +(1 + 2 * (1 << pow2)) * sizeof(SkPoint)ConvertConicToQuads returns Quad count used the approximation, which may be smaller +than the number requested. +Conic Weight determines the amount of influence Conic control point has on the curve. +w less than one represents an elliptical section. w greater than one represents +a hyperbolic section. w equal to one represents a parabolic section. + +Two Quad curves are sufficient to approximate an elliptical Conic with a sweep +of up to 90 degrees; in this case, set pow2 to one. + +### Parameters + + + + + + + + +
p0 +Conic start Point.
p1 +Conic control Point.
p2 +Conic end Point.
w +Conic weight.
pts +storage for Quad array.
pow2 +Quad count, as power of two, normally 0 to 5 (1 to 32 Quad curves).
+ +### Return Value + +Number of Quad curves written to pts. + +### Example + +
A pair of Quad curves are drawn in red on top of the elliptical Conic curve in black. +The middle curve is nearly circular. The top-right curve is parabolic, which can +be drawn exactly with a single Quad.
+ +### See Also + +Conic Quad + +--- + + +## isRect + +
+bool isRect(SkRect* rect, bool* isClosed = NULL, Direction* direction = NULL) const
+
+ +Returns true if Path is eqivalent to Rect when filled. +If isRect returns false: rect, isClosed, and direction are unchanged. +If isRect returns true: rect, isClosed, and direction are written to if not nullptr. + +rect may be smaller than the Path bounds. Path bounds may include kMove Verb points +that do not alter the area drawn by the returned rect. + +### Parameters + + + + + +
rect +storage for bounds of Rect; may be nullptr.
isClosed +storage set to true if Path is closed; may be nullptr
direction +storage set to Rect direction; may be nullptr.
+ +### Return Value + +true if Path contains Rect. + +### Example + +
After addRect, isRect returns true. Following moveTo permits isRect to return true, but +following lineTo does not. addPoly returns true even though rect is not closed, and one +side of rect is made up of consecutive line segments.
+ +#### Example Output + +~~~~ +empty is not rect +addRect is rect (10, 20, 30, 40); is closed; direction CW +moveTo is rect (10, 20, 30, 40); is closed; direction CW +lineTo is not rect +addPoly is rect (0, 0, 80, 80); is not closed; direction CCW +~~~~ + +
+ +### See Also + +computeTightBounds conservativelyContainsRect getBounds isConvex isLastContourClosed isNestedFillRects + +--- + + +## isNestedFillRects + +
+bool isNestedFillRects(SkRect rect[2], Direction dirs[2] = NULL) const
+
+ +Returns true if Path is equivalent to nested Rect pair when filled. +If isNestedFillRects returns false, rect and dirs are unchanged. +If isNestedFillRects returns true, rect and dirs are written to if not nullptr: +setting rect[0] to outer Rect, and rect[1] to inner Rect; +setting dirs[0] to Direction of outer Rect, and dirs[1] to Direction of inner +Rect. + +### Parameters + + + + +
rect +storage for Rect pair; may be nullptr.
dirs +storage for Direction pair; may be nullptr.
+ +### Return Value + +true if Path contains nested Rect pair. + +### Example + +
+ +#### Example Output + +~~~~ +outer (7.5, 17.5, 32.5, 42.5); direction CW +inner (12.5, 22.5, 27.5, 37.5); direction CCW +~~~~ + +
+ +### See Also + +computeTightBounds conservativelyContainsRect getBounds isConvex isLastContourClosed isRect + +--- + + +## addRect + +
+void addRect(const SkRect& rect, Direction dir = kCW_Direction)
+
+ +Add Rect to Path, appending kMove Verb, three kLine Verb, and kClose Verb, +starting with top-left corner of Rect; followed by top-right, bottom-right, +and bottom-left if dir is kCW Direction; or followed by bottom-left, +bottom-right, and top-right if dir is kCCW Direction. + +### Parameters + + + + +
rect +Rect to add as a closed contour.
dir +Direction to wind added contour.
+ +### Example + +
The left Rect dashes starting at the top-left corner, to the right. +The right Rect dashes starting at the top-left corner, towards the bottom.
+ +### See Also + +SkCanvas::drawRect Direction + +--- + +
+void addRect(const SkRect& rect, Direction dir, unsigned start)
+
+ +Add Rect to Path, appending kMove Verb, three kLine Verb, and kClose Verb. +If dir is kCW Direction, Rect corners are added clockwise; if dir is +kCCW Direction, Rect corners are added counterclockwise. +start determines the first corner added. + +| start | first corner | +| --- | --- | +| 0 | top-left | +| 1 | top-right | +| 2 | bottom-right | +| 3 | bottom-left | + +### Parameters + + + + + +
rect +Rect to add as a closed contour.
dir +Direction to wind added contour.
start +Initial corner of Rect to add.
+ +### Example + +
The arrow is just after the initial corner and points towards the next +corner appended to Path.
+ +### See Also + +SkCanvas::drawRect Direction + +--- + +
+void addRect(SkScalar left, SkScalar top, SkScalar right, SkScalar bottom,
+             Direction dir = kCW_Direction)
+
+ +Add Rect (left, top, right, bottom) to Path, +appending kMove Verb, three kLine Verb, and kClose Verb, +starting with top-left corner of Rect; followed by top-right, bottom-right, +and bottom-left if dir is kCW Direction; or followed by bottom-left, +bottom-right, and top-right if dir is kCCW Direction. + +### Parameters + + + + + + + +
left +smaller x of Rect.
top +smaller y of Rect.
right +larger x of Rect.
bottom +larger y of Rect.
dir +Direction to wind added contour.
+ +### Example + +
The left Rect dashes start at the top-left corner, and continue to the right. +The right Rect dashes start at the top-left corner, and continue down.
+ +### See Also + +SkCanvas::drawRect Direction + +--- + + +## addOval + +
+void addOval(const SkRect& oval, Direction dir = kCW_Direction)
+
+ +Add Oval to path, appending kMove Verb, four kConic Verb, and kClose Verb. +Oval is upright ellipse bounded by Rect oval with radii equal to half oval width +and half oval height. Oval begins at (oval.fRight, oval.centerY()) and continues +clockwise if dir is kCW Direction, counterclockwise if dir is kCCW Direction. + +This form is identical to + +### Parameters + + + + +
oval +bounds of ellipse added.
dir +Direction to wind ellipse.
+ +### Example + +
+ +### See Also + +SkCanvas::drawOval Direction Oval + +--- + +
+void addOval(const SkRect& oval, Direction dir, unsigned start)
+
+ +Add Oval to Path, appending kMove Verb, four kConic Verb, and kClose Verb. +Oval is upright ellipse bounded by Rect oval with radii equal to half oval width +and half oval height. Oval begins at start and continues +clockwise if dir is kCW Direction, counterclockwise if dir is kCCW Direction. + +| start | Point | +| --- | --- | +| 0 | oval.centerX(), oval.fTop | +| 1 | oval.fRight, oval.centerY() | +| 2 | oval.centerX(), oval.fBottom | +| 3 | oval.fLeft, oval.centerY() | + +### Parameters + + + + + +
oval +bounds of ellipse added.
dir +Direction to wind ellipse.
start +index of initial point of ellipse.
+ +### Example + +
+ +### See Also + +SkCanvas::drawOval Direction Oval + +--- + + +## addCircle + +
+void addCircle(SkScalar x, SkScalar y, SkScalar radius,
+               Direction dir = kCW_Direction)
+
+ +Add Circle centered at (x, y) of size radius to Path, appending kMove Verb, +four kConic Verb, and kClose Verb. Circle begins at (x + radius, y) and +continues clockwise if dir is kCW Direction, counterclockwise if dir is +kCCW Direction. + +addCircle has no effect if radius is zero or negative. + +### Parameters + + + + + + +
x +center of Circle.
y +center of Circle.
radius +distance from center to edge.
dir +Direction to wind Circle.
+ +### Example + +
+ +### See Also + +SkCanvas::drawCircle Direction Circle + +--- + + +## addArc + +
+void addArc(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle)
+
+ +Append Arc to Path, as the start of new Contour. Arc added is part of ellipse +bounded by oval, from startAngle through sweepAngle. Both startAngle and +sweepAngle are measured in degrees, where zero degrees is aligned with the +positive x-axis, and positive sweeps extends Arc clockwise. + +If sweepAngle <= -360, or sweepAngle >= 360; and startAngle modulo 90 is nearly +zero, append Oval instead of Arc. Otherwise, sweepAngle values are treated +modulo 360, and Arc may or may not draw depending on numeric rounding. + +### Parameters + + + + + +
oval +bounds of ellipse containing Arc.
startAngle +starting angle of Arc in degrees.
sweepAngle +sweep, in degrees. Positive is clockwise; treated modulo 360.
+ +### Example + +
The middle row of the left and right columns draw differently from the entries +above and below because sweepAngle is outside of the range of +/-360, +and startAngle modulo 90 is not zero.
+ +### See Also + +Arc arcTo SkCanvas::drawArc + +--- + + +## addRoundRect + +
+void addRoundRect(const SkRect& rect, SkScalar rx, SkScalar ry,
+                  Direction dir = kCW_Direction)
+
+ +Append Round Rect to Path, creating a new closed Contour. Round Rect has bounds +equal to rect; each corner is 90 degrees of an ellipse with radii (rx, ry). If +dir is kCW Direction, Round Rect starts at top-left of the lower-left corner and +winds clockwise. If dir is kCCW Direction, Round Rect starts at the bottom-left +of the upper-left corner and winds counterclockwise. + +If either rx or ry is too large, rx and ry are scaled uniformly until the +corners fit. If rx or ry is less than or equal to zero, addRoundRect appends +Rect rect to Path. + +After appending, Path may be empty, or may contain: Rect, Oval, or RoundRect. + +### Parameters + + + + + + +
rect +bounds of Round Rect.
rx +x-radius of rounded corners on the Round Rect
ry +y-radius of rounded corners on the Round Rect
dir +Direction to wind Round Rect.
+ +### Example + +
If either radius is zero, path contains Rect and is drawn red. +If sides are only radii, path contains Oval and is drawn blue. +All remaining path draws are convex, and are drawn in gray; no +paths constructed from addRoundRect are concave, so none are +drawn in green.
+ +### See Also + +addRRect SkCanvas::drawRoundRect + +--- + +
+void addRoundRect(const SkRect& rect, const SkScalar radii[],
+                  Direction dir = kCW_Direction)
+
+ +Append Round Rect to Path, creating a new closed Contour. Round Rect has bounds +equal to rect; each corner is 90 degrees of an ellipse with radii from the +array. + +| radii index | location | +| --- | --- | +| 0 | x-radius of top-left corner | +| 1 | y-radius of top-left corner | +| 2 | x-radius of top-right corner | +| 3 | y-radius of top-right corner | +| 4 | x-radius of bottom-right corner | +| 5 | y-radius of bottom-right corner | +| 6 | x-radius of bottom-left corner | +| 7 | y-radius of bottom-left corner | + +If dir is kCW Direction, Round Rect starts at top-left of the lower-left corner +and winds clockwise. If dir is kCCW Direction, Round Rect starts at the +bottom-left of the upper-left corner and winds counterclockwise. + +If both radii on any side of rect exceed its length, all radii are scaled +uniformly until the corners fit. If either radius of a corner is less than or +equal to zero, both are treated as zero. + +After appending, Path may be empty, or may contain: Rect, Oval, or RoundRect. + +### Parameters + + + + + +
rect +bounds of Round Rect.
radii +array of 8 SkScalar values, a radius pair for each corner.
dir +Direction to wind Round Rect.
+ +### Example + +
+ +### See Also + +addRRect SkCanvas::drawRoundRect + +--- + + +## addRRect + +
+void addRRect(const SkRRect& rrect, Direction dir = kCW_Direction)
+
+ +Add rrect to Path, creating a new closed Contour. If +dir is kCW Direction, rrect starts at top-left of the lower-left corner and +winds clockwise. If dir is kCCW Direction, rrect starts at the bottom-left +of the upper-left corner and winds counterclockwise. + +After appending, Path may be empty, or may contain: Rect, Oval, or RRect. + +### Parameters + + + + +
rrect +bounds and radii of rounded rectangle.
dir +Direction to wind Round Rect.
+ +### Example + +
+ +### See Also + +addRoundRect SkCanvas::drawRRect + +--- + +
+void addRRect(const SkRRect& rrect, Direction dir, unsigned start)
+
+ +Add rrect to Path, creating a new closed Contour. If dir is kCW Direction, rrect +winds clockwise; if dir is kCCW Direction, rrect winds counterclockwise. +start determines the first point of rrect to add. + +| start | location | +| --- | --- | +| 0 | right of top-left corner | +| 1 | left of top-right corner | +| 2 | bottom of top-right corner | +| 3 | top of bottom-right corner | +| 4 | left of bottom-right corner | +| 5 | right of bottom-left corner | +| 6 | top of bottom-left corner | +| 7 | bottom of top-left corner | + +After appending, Path may be empty, or may contain: Rect, Oval, or RRect. + +### Parameters + + + + + +
rrect +bounds and radii of rounded rectangle.
dir +Direction to wind RRect.
start +Index of initial point of RRect.
+ +### Example + +
+ +### See Also + +addRoundRect SkCanvas::drawRRect + +--- + + +## addPoly + +
+void addPoly(const SkPoint pts[], int count, bool close)
+
+ +Add Contour created from Line Array. Given count pts, addPoly adds +count - 1 Line segments. Contour added starts at pt[0], then adds a line +for every additional Point in pts array. If close is true, addPoly +appends kClose Verb to Path, connecting pts[count - 1] and pts[0]. + +If count is zero, append kMove Verb to path. +addPoly has no effect if count is less than one. + +### Parameters + + + + + +
pts +Array of Line sharing end and start Point.
count +Length of Point array.
close +true to add Line connecting Contour end and start.
+ +### Example + +
+ +### See Also + +SkCanvas::drawPoints + +--- + +## Enum SkPath::AddPathMode + +
+enum AddPathMode {
+kAppend AddPathMode 
+kExtend AddPathMode 
+};
+ +AddPathMode chooses how addPath appends. Adding one Path to another can extend +the last Contour or start a new Contour. + +### Constants + + + + + + + + +
SkPath::kAppend_AddPathMode Path Verbs, Points, and Weights are appended to destination unaltered.Since Path Verb Array begins with kMove Verb if src is not empty, this +starts a new Contour.
SkPath::kExtend_AddPathMode If destination is closed or empty, start a new Contour. If destinationis not empty, add Line from Last Point to added Path first Point. Skip added +Path initial kMove Verb, then append remining Verbs, Points, and Weights.
+ +### Example + +
test is built from path, open on the top row, and closed on the bottom row. +The left column uses kAppend AddPathMode; the right uses kExtend AddPathMode. +The top right composition is made up of one contour; the other three have two.
+ +### See Also + +addPath reverseAddPath + + + + +## addPath + +
+void addPath(const SkPath& src, SkScalar dx, SkScalar dy,
+             AddPathMode mode = kAppend_AddPathMode)
+
+ +Append src to Path, offset by (dx, dy). + +If mode is kAppend AddPathMode, src Verb Array, Point Array, and Weights are +added unaltered. If mode is kExtend AddPathMode, add Line before appending +Verbs, Points, and Weights. + +### Parameters + + + + + + +
src +Path Verbs, Points, and Weights to add.
dx +offset added to src Point Array x coordinates.
dy +offset added to src Point Array y coordinates.
mode +kAppend AddPathMode or kExtend AddPathMode.
+ +### Example + +
+ +### See Also + +AddPathMode offset reverseAddPath + +--- + +
+void addPath(const SkPath& src, AddPathMode mode = kAppend_AddPathMode)
+
+ +Append src to Path. + +If mode is kAppend AddPathMode, src Verb Array, Point Array, and Weights are +added unaltered. If mode is kExtend AddPathMode, add Line before appending +Verbs, Points, and Weights. + +### Parameters + + + + +
src +Path Verbs, Points, and Weights to add.
mode +kAppend AddPathMode or kExtend AddPathMode.
+ +### Example + +
+ +### See Also + +AddPathMode reverseAddPath + +--- + +
+void addPath(const SkPath& src, const SkMatrix& matrix,
+             AddPathMode mode = kAppend_AddPathMode)
+
+ +Append src to Path, transformed by matrix. Transformed curves may have different +Verbs, Points, and Weights. + +If mode is kAppend AddPathMode, src Verb Array, Point Array, and Weights are +added unaltered. If mode is kExtend AddPathMode, add Line before appending +Verbs, Points, and Weights. + +### Parameters + + + + + +
src +Path Verbs, Points, and Weights to add.
matrix +Transform applied to src.
mode +kAppend AddPathMode or kExtend AddPathMode.
+ +### Example + +
+ +### See Also + +AddPathMode transform offset reverseAddPath + +--- + + +## reverseAddPath + +
+void reverseAddPath(const SkPath& src)
+
+ +Append src to Path, from back to front. +Reversed src always appends a new Contour to Path. + +### Parameters + + + +
src +Path Verbs, Points, and Weights to add.
+ +### Example + +
+ +### See Also + +AddPathMode transform offset addPath + +--- + + +## offset + +
+void offset(SkScalar dx, SkScalar dy, SkPath* dst) const
+
+ +Offset Point Array by (dx, dy). Offset Path replaces dst. +If dst is nullptr, Path is replaced by offset data. + +### Parameters + + + + + +
dx +offset added to Point Array x coordinates.
dy +offset added to Point Array y coordinates.
dst +overwritten, translated copy of Path; may be nullptr.
+ +### Example + +
+ +### See Also + +addPath transform + +--- + +
+void offset(SkScalar dx, SkScalar dy)
+
+ +Offset Point Array by (dx, dy). Path is replaced by offset data. + +### Parameters + + + + +
dx +offset added to Point Array x coordinates.
dy +offset added to Point Array y coordinates.
+ +### Example + +
+ +### See Also + +addPath transform SkCanvas::translate() + +--- + + +## transform + +
+void transform(const SkMatrix& matrix, SkPath* dst) const
+
+ +Transform Verb Array, Point Array, and weight by matrix. +transform may change Verbs and increase their number. +Transformed Path replaces dst; if dst is nullptr, original data +is replaced. + +### Parameters + + + + +
matrix +Matrix to apply to Path.
dst +overwritten, transformed copy of Path; may be nullptr.
+ +### Example + +
+ +### See Also + +addPath offset SkCanvas::concat() SkMatrix + +--- + +
+void transform(const SkMatrix& matrix)
+
+ +Transform Verb Array, Point Array, and weight by matrix. +transform may change Verbs and increase their number. +Path is replaced by transformed data. + +### Parameters + + + +
matrix +Matrix to apply to Path.
+ +### Example + +
+ +### See Also + +addPath offset SkCanvas::concat() SkMatrix + +--- + +## Last Point + +Path is defined cumulatively, often by adding a segment to the end of last +Contour. Last Point of Contour is shared as first Point of added Line or Curve. +Last Point can be read and written directly with getLastPt and setLastPt. + + +## getLastPt + +
+bool getLastPt(SkPoint* lastPt) const
+
+ +Returns Last Point on Path in lastPt. Returns false if Point Array is empty, +storing (0, 0) if lastPt is not nullptr. + +### Parameters + + + +
lastPt +storage for final Point in Point Array; may be nullptr.
+ +### Return Value + +true if Point Array contains one or more Points. + +### Example + +
+ +#### Example Output + +~~~~ +last point: 35.2786, 52.9772 +~~~~ + +
+ +### See Also + +setLastPt + +--- + + +## setLastPt + +
+void setLastPt(SkScalar x, SkScalar y)
+
+ +Set Last Point to (x, y). If Point Array is empty, append kMove Verb to +Verb Array and (x, y) to Point Array. + +### Parameters + + + + +
x +set x-coordinate of Last Point.
y +set y-coordinate of Last Point.
+ +### Example + +
+ +### See Also + +getLastPt + +--- + +
+void setLastPt(const SkPoint& p)
+
+ +Set the last point on the path. If no points have been added, + +### Parameters + + + +
p +set value of Last Point.
+ +### Example + +
+ +### See Also + +getLastPt + +--- + +## Enum SkPath::SegmentMask + +
+enum SegmentMask {
+kLine SegmentMask = 1 << 0
+kQuad SegmentMask = 1 << 1
+kConic SegmentMask = 1 << 2
+kCubic SegmentMask = 1 << 3
+};
+ +SegmentMask constants correspond to each drawing Verb type in Path; for +instance, if Path only contains Lines, only the kLine SegmentMask bit is set. + +### Constants + + + + + + + + + + + + + + +
SkPath::kLine_SegmentMask 1Set if Verb Array contains kLine Verb.
SkPath::kQuad_SegmentMask 2Set if Verb Array contains kQuad Verb. Note that conicTo may add a Quad.
SkPath::kConic_SegmentMask 4Set if Verb Array contains kConic Verb.
SkPath::kCubic_SegmentMask 8Set if Verb Array contains kCubic Verb.
+ +### Example + +
When conicTo has a weight of one, Quad is added to Path.
+ +#### Example Output + +~~~~ +Path kConic_SegmentMask is clear +Path kQuad_SegmentMask is set +~~~~ + +
+ +### See Also + +getSegmentMasks Verb + + + + +## getSegmentMasks + +
+uint32_t getSegmentMasks() const
+
+ +Returns a mask, where each set bit corresponds to a SegmentMask constant +if Path contains one or more Verbs of that type. +Returns zero if Path contains no Lines, Quads, Conics, or Cubics. + +getSegmentMasks returns a cached result; it is very fast. + +### Return Value + +SegmentMask bits or zero. + +### Example + +
+ +#### Example Output + +~~~~ +mask quad set +~~~~ + +
+ +### See Also + +getSegmentMasks Verb + +--- + + +## contains + +
+bool contains(SkScalar x, SkScalar y) const
+
+ +Returns true if the point (x, y) is contained by Path, taking into +account FillType. + +| FillType | contains returns true if Point is enclosed by | +| --- | --- | +| kWinding FillType | a non-zero sum of Contour Directions. | +| kEvenOdd FillType | an odd number of Contours. | +| kInverseWinding FillType | a zero sum of Contour Directions. | +| kInverseEvenOdd FillType | and even number of Contours. | + +### Parameters + + + + +
x +x-coordinate of containment test.
y +y-coordinate of containment test.
+ +### Return Value + +true if Point is in Path. + +### Example + +
+ +### See Also + +conservativelyContainsRect Fill Type Op + +--- + + +## dump + +
+void dump(SkWStream* stream, bool forceClose, bool dumpAsHex) const
+
+ +Writes text representation of Path to stream. If stream is nullptr, dump writes to +stdout. Set forceClose to true to get +edges used to fill Path. Set dumpAsHex true to get exact binary representations +of floating point numbers used in Point Array and Weights. + +### Parameters + + + + + +
stream +writable Stream receiving Path text representation; may be nullptr.
forceClose +true if missing kClose Verb is output.
dumpAsHex +true if SkScalar values are written as hexidecimal.
+ +### Example + +
+ +#### Example Output + +~~~~ +path.setFillType(SkPath::kWinding_FillType); +path.moveTo(0, 0); +path.quadTo(20, 30, 40, 50); +path.setFillType(SkPath::kWinding_FillType); +path.moveTo(SkBits2Float(0x00000000), SkBits2Float(0x00000000)); // 0, 0 +path.quadTo(SkBits2Float(0x41a00000), SkBits2Float(0x41f00000), SkBits2Float(0x42200000), SkBits2Float(0x42480000)); // 20, 30, 40, 50 +path.setFillType(SkPath::kWinding_FillType); +path.moveTo(0, 0); +path.quadTo(20, 30, 40, 50); +path.lineTo(0, 0); +path.close(); +path.setFillType(SkPath::kWinding_FillType); +path.moveTo(SkBits2Float(0x00000000), SkBits2Float(0x00000000)); // 0, 0 +path.quadTo(SkBits2Float(0x41a00000), SkBits2Float(0x41f00000), SkBits2Float(0x42200000), SkBits2Float(0x42480000)); // 20, 30, 40, 50 +path.lineTo(SkBits2Float(0x00000000), SkBits2Float(0x00000000)); // 0, 0 +path.close(); +~~~~ + +
+ +### See Also + +SkRect::dump() SkRRect::dump() SkPathMeasure::dump() + +--- + +
+void dump() const
+
+ +Writes text representation of Path to stdout. The representation may be +directly compiled as C++ code. Floating point values are written +with limited precision; it may not be possible to reconstruct original Path +from output. + +### Example + +
+ +#### Example Output + +~~~~ +path.setFillType(SkPath::kWinding_FillType); +path.moveTo(0, 0); +path.lineTo(0.857143f, 0.666667f); +path is not equal to copy +~~~~ + +
+ +### See Also + +dumpHex SkRect::dump() SkRRect::dump() SkPathMeasure::dump() writeToMemory + +--- + + +## dumpHex + +
+void dumpHex() const
+
+ +Writes text representation of Path to stdout. The representation may be +directly compiled as C++ code. Floating point values are written +in hexadecimal to preserve their exact bit pattern. The output reconstructs the +original Path. + +Use dumpHex when submittingbug reports against Skiahttp://bug.skia.org. +Slight value changes in Point Array may cause the bug to disappear. + +### Example + +
+ +#### Example Output + +~~~~ +path.setFillType(SkPath::kWinding_FillType); +path.moveTo(SkBits2Float(0x00000000), SkBits2Float(0x00000000)); // 0, 0 +path.lineTo(SkBits2Float(0x3f5b6db7), SkBits2Float(0x3f2aaaab)); // 0.857143f, 0.666667f +path is equal to copy +~~~~ + +
+ +### See Also + +dump + +--- + + +## writeToMemory + +
+size_t writeToMemory(void* buffer) const
+
+ +Write Path to buffer, returning the number of bytes written. +Pass nullptr to obtain the storage size. + +writeToMemory writes Fill Type, Verb Array, Point Array, Conic Weight, and +additionally writes computed information like Convexity and bounds. + +writeToMemory should only be used in concert with readFromMemory. +The format used for Path in memory is not guaranteed. + +### Parameters + + + +
buffer +storage for Path; may be nullptr.
+ +### Return Value + +size of storage required for Path; always a multiple of 4. + +### Example + +
+ +### See Also + +readFromMemory dump dumpHex + +--- + + +## readFromMemory + +
+size_t readFromMemory(const void* buffer, size_t length)
+
+ +Initializes Path from buffer of size length. Returns zero if the buffer is +data is inconsistent, or the length is too small. + +readFromMemory reads Fill Type, Verb Array, Point Array, Conic Weight, and +additionally reads computed information like Convexity and bounds. + +readFromMemory should only be used in concert with writeToMemory. +The format used for Path in memory is not guaranteed. + +### Parameters + + + + +
buffer +storage for Path.
length +buffer size in bytes; must be multiple of 4.
+ +### Return Value + +number of bytes read, or zero on failure. + +### Example + +
+ +#### Example Output + +~~~~ +length = 60; returned by readFromMemory = 0 +length = 68; returned by readFromMemory = 64 +~~~~ + +
+ +### See Also + +writeToMemory + +--- + +# Generation ID +Generation ID provides a quick way to check if Verb Array, Point Array, or +Conic Weight has changed. Generation ID is not a hash; identical Paths will +not necessarily have matching Generation IDs. + +Empty Paths have a Generation ID of one. + + +## getGenerationID + +
+uint32_t getGenerationID() const
+
+ +Returns a non-zero, globally unique value. A different value is returned +if Verb Array, Point Array, or Conic Weight changes. + +Setting Fill Type does not change Generation ID. + +Each time the path is modified, a different Generation ID will be returned. + +### Return Value + +non-zero, globally unique value. + +### Example + +
+ +#### Example Output + +~~~~ +empty genID = 1 +1st lineTo genID = 2 +empty genID = 1 +2nd lineTo genID = 3 +~~~~ + +
+ +### See Also + +operator==(const SkPath& a, const SkPath& b) + +--- + + +## validate + +
+void validate() const
+
+ +Debugging check to see if Path data is consistent. +Not currently maintained. + +--- + + +## experimentalValidateRef + +
+void experimentalValidateRef() const
+
+ +--- + +# Class Iter +Iterates through Verb Array, and associated Point Array and Conic Weight. +Provides options to treat open Contours as closed, and to ignore +degenerate data. + +### Example + +
Ignoring the actual Verbs and replacing them with quads rounds the +path of the glyph.
+ +### See Also + +RawIter + + +## Iter + +
+Iter()
+
+ +Initializes Iter with an empty Path. next on Iter returns kDone Verb. +Call setPath to initialize Iter at a later time. + +### Return Value + +Iter of empty Path. + +### Example + +
+ +#### Example Output + +~~~~ +iter is done +iter is done +~~~~ + +
+ +### See Also + +setPath + +--- + + +## Iter + +
+Iter(const SkPath& path, bool forceClose)
+
+ +Sets Iter to return elements of Verb Array, Point Array, and Conic Weight in path. +If forceClose is true, Iter will add kLine Verb and kClose Verb after each +open Contour. path is not altered. + +### Parameters + + + + +
path +Path to iterate.
forceClose +true if open Contours generate kClose Verb.
+ +### Return Value + +Iter of path. + +### Example + +
+ +#### Example Output + +~~~~ +open: +kMove_Verb {0, 0}, +kQuad_Verb {0, 0}, {10, 20}, {30, 40}, +kDone_Verb +closed: +kMove_Verb {0, 0}, +kQuad_Verb {0, 0}, {10, 20}, {30, 40}, +kLine_Verb {30, 40}, {0, 0}, +kClose_Verb {0, 0}, +kDone_Verb +~~~~ + +
+ +### See Also + +setPath + +--- + + +## setPath + +
+void setPath(const SkPath& path, bool forceClose)
+
+ +Sets Iter to return elements of Verb Array, Point Array, and Conic Weight in path. +If forceClose is true, Iter will add kLine Verb and kClose Verb after each +open Contour. path is not altered. + +### Parameters + + + + +
path +Path to iterate.
forceClose +true if open Contours generate kClose Verb.
+ +### Example + +
+ +#### Example Output + +~~~~ +quad open: +kMove_Verb {0, 0}, +kQuad_Verb {0, 0}, {10, 20}, {30, 40}, +kDone_Verb +conic closed: +kMove_Verb {0, 0}, +kConic_Verb {0, 0}, {1, 2}, {3, 4}, weight = 0.5 +kLine_Verb {3, 4}, {0, 0}, +kClose_Verb {0, 0}, +kDone_Verb +~~~~ + +
+ +### See Also + +Iter(const SkPath& path, bool forceClose) + +--- + + +## next + +
+Verb next(SkPoint pts[4], bool doConsumeDegenerates = true, bool exact = false)
+
+ +Returns next Verb in Verb Array, and advances Iter. +When Verb Array is exhausted, returns kDone Verb. +Zero to four Points are stored in pts, depending on the returned Verb. +If doConsumeDegenerates is true, skip consecutive kMove Verb entries, returning +only the last in the series; and skip very small Lines, Quads, and Conics; and +skip kClose Verb following kMove Verb. +if doConsumeDegenerates is true and exact is true, only skip Lines, Quads, and +Conics with zero lengths. + +### Parameters + + + + + +
pts +Storage for Point data describing returned Verb.
doConsumeDegenerates +If true, skip degenerate Verbs.
exact +If true, skip zero length curves. Has no effect if doConsumeDegenerates +is false.
+ +### Return Value + +next Verb from Verb Array. + +### Example + +
skip degenerate skips the first in a kMove Verb pair, the kMove Verb +followed by the kClose Verb, the zero length Line and the very small Line. + +skip degenerate if exact skips the same as skip degenerate, but shows +the very small Line. + +skip none shows all of the Verbs and Points in Path.
+ +#### Example Output + +~~~~ +skip degenerate: +kMove_Verb {20, 20}, +kQuad_Verb {20, 20}, {10, 20}, {30, 40}, +kDone_Verb +skip degenerate if exact: +kMove_Verb {20, 20}, +kQuad_Verb {20, 20}, {10, 20}, {30, 40}, +kMove_Verb {30, 30}, +kLine_Verb {30, 30}, {30.00001, 30}, +kDone_Verb +skip none: +kMove_Verb {10, 10}, +kMove_Verb {20, 20}, +kQuad_Verb {20, 20}, {10, 20}, {30, 40}, +kMove_Verb {1, 1}, +kClose_Verb {1, 1}, +kMove_Verb {30, 30}, +kLine_Verb {30, 30}, {30, 30}, +kMove_Verb {30, 30}, +kLine_Verb {30, 30}, {30.00001, 30}, +kDone_Verb +~~~~ + +
+ +### See Also + +Verb IsLineDegenerate IsCubicDegenerate IsQuadDegenerate + +--- + + +## conicWeight + +
+SkScalar conicWeight() const
+
+ +Returns Conic Weight if next returned kConic Verb. + +If next has not been called, or next did not return kConic Verb, +result is undefined. + +### Return Value + +Conic Weight for Conic Points returned by next. + +### Example + +
+ +#### Example Output + +~~~~ +first verb is move +next verb is conic +conic points: {0,0}, {1,2}, {3,4} +conic weight: 0.5 +~~~~ + +
+ +### See Also + +Conic Weight + +--- + + +## isCloseLine + +
+bool isCloseLine() const
+
+ +Returns true if last kLine Verb returned by next was generated +by kClose Verb. When true, the end point returned by next is +also the start point of Contour. + +If next has not been called, or next did not return kLine Verb, +result is undefined. + +### Return Value + +true if last kLine Verb was generated by kClose Verb. + +### Example + +
+ +#### Example Output + +~~~~ +1st verb is move +moveTo point: {6,7} +2nd verb is conic +3rd verb is line +line points: {3,4}, {6,7} +line generated by close +4th verb is close +~~~~ + +
+ +### See Also + +close + +--- + + +## isClosedContour + +
+bool isClosedContour() const
+
+ +Returns true if subsequent calls to next return kClose Verb before returning +kMove Verb. if true, Contour Iter is processing may end with kClose Verb, or +Iter may have been initialized with force close set to true. + +### Return Value + +true if Contour is closed. + +### Example + +
+ +#### Example Output + +~~~~ +without close(), forceClose is false: isClosedContour returns false +with close(), forceClose is false: isClosedContour returns true +without close(), forceClose is true : isClosedContour returns true +with close(), forceClose is true : isClosedContour returns true +~~~~ + +
+ +### See Also + +Iter(const SkPath& path, bool forceClose) + +--- + +# Class RawIter +Iterates through Verb Array, and associated Point Array and Conic Weight. +Verb Array, Point Array, and Conic Weight are returned unaltered. + + +## RawIter + +
+RawIter()
+
+ +Initializes RawIter with an empty Path. next on RawIter returns kDone Verb. +Call setPath to initialize Iter at a later time. + +### Return Value + +RawIter of empty Path. + +--- + + +## RawIter + +
+RawIter(const SkPath& path)
+
+ +Sets RawIter to return elements of Verb Array, Point Array, and Conic Weight in path. + +### Parameters + + + +
path +Path to iterate.
+ +### Return Value + +RawIter of path. + +--- + + +## setPath + +
+void setPath(const SkPath& path)
+
+ +Sets Iter to return elements of Verb Array, Point Array, and Conic Weight in path. + +### Parameters + + + +
path +Path to iterate.
+ +--- + + +## next + +
+Verb next(SkPoint pts[4])
+
+ +Returns next Verb in Verb Array, and advances RawIter. +When Verb Array is exhausted, returns kDone Verb. +Zero to four Points are stored in pts, depending on the returned Verb. + +### Parameters + + + +
pts +Storage for Point data describing returned Verb.
+ +### Return Value + +next Verb from Verb Array. + +### Example + +
+ +#### Example Output + +~~~~ +kMove_Verb {50, 60}, +kQuad_Verb {50, 60}, {10, 20}, {30, 40}, +kClose_Verb {50, 60}, +kMove_Verb {50, 60}, +kLine_Verb {50, 60}, {30, 30}, +kConic_Verb {30, 30}, {1, 2}, {3, 4}, weight = 0.5 +kCubic_Verb {3, 4}, {-1, -2}, {-3, -4}, {-5, -6}, +kDone_Verb +~~~~ + +
+ +### See Also + +peek + +--- + + +## peek + +
+Verb peek() const
+
+ +Returns next Verb, but does not advance RawIter. + +### Return Value + +next Verb from Verb Array. + +### Example + +
+ +#### Example Output + +~~~~ +#Volatile +peek Move == verb Move +peek Quad == verb Quad +peek Conic == verb Conic +peek Cubic == verb Cubic +peek Done == verb Done +peek Done == verb Done +~~~~ + +
+ +### See Also + +next + +--- + + +## conicWeight + +
+SkScalar conicWeight() const
+
+ +Returns Conic Weight if next returned kConic Verb. + +If next has not been called, or next did not return kConic Verb, +result is undefined. + +### Return Value + +Conic Weight for Conic Points returned by next. + +### Example + +
+ +#### Example Output + +~~~~ +first verb is move +next verb is conic +conic points: {0,0}, {1,2}, {3,4} +conic weight: 0.5 +~~~~ + +
+ +### See Also + +Conic Weight + +--- + diff --git a/site/user/api/canvas.md b/site/user/api/canvas.md deleted file mode 100644 index d6aa7b6b7c..0000000000 --- a/site/user/api/canvas.md +++ /dev/null @@ -1,264 +0,0 @@ -Creating SkCanvas Objects -========================= - -First, read about [the SkCanvas API](skcanvas). - -Skia has multiple backends which receive SkCanvas drawing commands, -including: - -- [Raster](#raster) - CPU-only. -- [GPU](#gpu) - Skia's GPU-accelerated backend. -- [SkPDF](#skpdf) - PDF document creation. -- [SkPicture](#skpicture) - Skia's display list format. -- [NullCanvas](#nullcanvas) - Useful for testing only. -- [SkXPS](#skxps) - Experimental XPS backend. -- [SkSVG](#sksvg) - Experimental XPS backend. - -Each backend has a unique way of creating a SkCanvas. This page gives -an example for each: - - -Raster ------- - -The raster backend draws to a block of memory. This memory can be -managed by Skia or by the client. - -The recommended way of creating a canvas for the Raster and Ganesh -backends is to use a `SkSurface`, which is an object that manages -the memory into which the canvas commands are drawn. - - - - #include "SkData.h" - #include "SkImage.h" - #include "SkStream.h" - #include "SkSurface.h" - void raster(int width, int height, - void (*draw)(SkCanvas*), - const char* path) { - sk_sp rasterSurface = - SkSurface::MakeRasterN32Premul(width, height); - SkCanvas* rasterCanvas = rasterSurface->getCanvas(); - draw(rasterCanvas); - sk_sp img(rasterSurface->makeImageSnapshot()); - if (!img) { return; } - sk_sp png(img->encode()); - if (!png) { return; } - SkFILEWStream out(path); - (void)out.write(png->data(), png->size()); - } - -Alternatively, we could have specified the memory for the surface -explicitly, instead of asking Skia to manage it. - - - - #include - #include "SkSurface.h" - std::vector raster_direct(int width, int height, - void (*draw)(SkCanvas*)) { - SkImageInfo info = SkImageInfo::MakeN32Premul(width, height); - size_t rowBytes = info.minRowBytes(); - size_t size = info.getSafeSize(rowBytes); - std::vector pixelMemory(size); // allocate memory - sk_sp surface = - SkSurface::MakeRasterDirect( - info, &pixelMemory[0], rowBytes); - SkCanvas* canvas = surface->getCanvas(); - draw(canvas); - return pixelMemory; - } - - -GPU ------- - -GPU Surfaces must have a `GrContext` object which manages the -GPU context, and related caches for textures and fonts. GrContexts -are matched one to one with OpenGL contexts or Vulkan devices. That is, all -SkSurfaces that will be rendered to using the same OpenGL context or Vulkan -device should share a GrContext. Skia does not create a OpenGL context or Vulkan -device for you. In OpenGL mode it also assumes that the correct OpenGL context -has been made current to the current thread when Skia calls are made. - - - - #include "GrContext.h" - #include "gl/GrGLInterface.h" - #include "SkData.h" - #include "SkImage.h" - #include "SkStream.h" - #include "SkSurface.h" - - void gl_example(int width, int height, void (*draw)(SkCanvas*), const char* path) { - // You've already created your OpenGL context and bound it. - const GrGLInterface* interface = nullptr; - // Leaving interface as null makes Skia extract pointers to OpenGL functions for the current - // context in a platform-specific way. Alternatively, you may create your own GrGLInterface and - // initialize it however you like to attach to an alternate OpenGL implementation or intercept - // Skia's OpenGL calls. - sk_sp context = GrContext::MakeGL(interface); - SkImageInfo info = SkImageInfo:: MakeN32Premul(width, height); - sk_sp gpuSurface( - SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, info)); - if (!gpuSurface) { - SkDebugf("SkSurface::MakeRenderTarget returned null\n"); - return; - } - SkCanvas* gpuCanvas = gpuSurface->getCanvas(); - draw(gpuCanvas); - sk_sp img(gpuSurface->makeImageSnapshot()); - if (!img) { return; } - sk_sp png(img->encode()); - if (!png) { return; } - SkFILEWStream out(path); - (void)out.write(png->data(), png->size()); - } - - -SkPDF ------ - -The SkPDF backend uses `SkDocument` instead of `SkSurface`, since -a document must include multiple pages. - - - - #include "SkDocument.h" - #include "SkStream.h" - void skpdf(int width, int height, - void (*draw)(SkCanvas*), - const char* path) { - SkFILEWStream pdfStream(path); - sk_sp pdfDoc = SkDocument::MakePDF(&pdfStream); - SkCanvas* pdfCanvas = pdfDoc->beginPage(SkIntToScalar(width), - SkIntToScalar(height)); - draw(pdfCanvas); - pdfDoc->close(); - } - - -SkPicture ---------- - -The SkPicture backend uses SkPictureRecorder instead of SkSurface. - - - - #include "SkPictureRecorder.h" - #include "SkPicture.h" - #include "SkStream.h" - void picture(int width, int height, - void (*draw)(SkCanvas*), - const char* path) { - SkPictureRecorder recorder; - SkCanvas* recordingCanvas = recorder.beginRecording(SkIntToScalar(width), - SkIntToScalar(height)); - draw(recordingCanvas); - sk_sp picture = recorder.finishRecordingAsPicture(); - SkFILEWStream skpStream(path); - // Open SKP files with `SampleApp --picture SKP_FILE` - picture->serialize(&skpStream); - } - - -NullCanvas ----------- - -The null canvas is a canvas that ignores all drawing commands and does -nothing. - - - - #include "SkNullCanvas.h" - void null_canvas_example(int, int, void (*draw)(SkCanvas*), const char*) { - std::unique_ptr nullCanvas = SkMakeNullCanvas(); - draw(nullCanvas.get()); // NoOp - } - - -SkXPS ------ - -The (*still experimental*) SkXPS canvas writes into an XPS document. - - - - #include "SkDocument.h" - #include "SkStream.h" - #ifdef SK_BUILD_FOR_WIN - void skxps(IXpsOMObjectFactory* factory; - int width, int height, - void (*draw)(SkCanvas*), - const char* path) { - SkFILEWStream xpsStream(path); - sk_sp xpsDoc = SkDocument::MakeXPS(&pdfStream, factory); - SkCanvas* xpsCanvas = xpsDoc->beginPage(SkIntToScalar(width), - SkIntToScalar(height)); - draw(xpsCanvas); - xpsDoc->close(); - } - #endif - - -SkSVG ------ - -The (*still experimental*) SkSVG canvas writes into an SVG document. - - - - #include "SkStream.h" - #include "SkSVGCanvas.h" - #include "SkXMLWriter.h" - void sksvg(int width, int height, - void (*draw)(SkCanvas*), - const char* path) { - SkFILEWStream svgStream(path); - std::unique_ptr xmlWriter( - new SkXMLStreamWriter(&svgStream)); - SkRect bounds = SkRect::MakeIWH(width, height); - std::unique_ptr svgCanvas = - SkSVGCanvas::Make(bounds, xmlWriter.get()); - draw(svgCanvas.get()); - } - - -Example -------- - -To try this code out, make a [new unit test using instructions -here](/dev/testing/tests) and wrap these funtions together: - - - - #include "SkCanvas.h" - #include "SkPath.h" - #include "Test.h" - void example(SkCanvas* canvas) { - const SkScalar scale = 256.0f; - const SkScalar R = 0.45f * scale; - const SkScalar TAU = 6.2831853f; - SkPath path; - for (int i = 0; i < 5; ++i) { - SkScalar theta = 2 * i * TAU / 5; - if (i == 0) { - path.moveTo(R * cos(theta), R * sin(theta)); - } else { - path.lineTo(R * cos(theta), R * sin(theta)); - } - } - path.close(); - SkPaint p; - p.setAntiAlias(true); - canvas->clear(SK_ColorWHITE); - canvas->translate(0.5f * scale, 0.5f * scale); - canvas->drawPath(path, p); - } - DEF_TEST(FourBackends, r) { - raster( 256, 256, example, "out_raster.png" ); - gl_example( 256, 256, example, "out_gpu.png" ); - skpdf( 256, 256, example, "out_skpdf.pdf" ); - picture( 256, 256, example, "out_picture.skp"); - } diff --git a/site/user/api/creating_skcanvas.md b/site/user/api/creating_skcanvas.md new file mode 100644 index 0000000000..d6aa7b6b7c --- /dev/null +++ b/site/user/api/creating_skcanvas.md @@ -0,0 +1,264 @@ +Creating SkCanvas Objects +========================= + +First, read about [the SkCanvas API](skcanvas). + +Skia has multiple backends which receive SkCanvas drawing commands, +including: + +- [Raster](#raster) - CPU-only. +- [GPU](#gpu) - Skia's GPU-accelerated backend. +- [SkPDF](#skpdf) - PDF document creation. +- [SkPicture](#skpicture) - Skia's display list format. +- [NullCanvas](#nullcanvas) - Useful for testing only. +- [SkXPS](#skxps) - Experimental XPS backend. +- [SkSVG](#sksvg) - Experimental XPS backend. + +Each backend has a unique way of creating a SkCanvas. This page gives +an example for each: + + +Raster +------ + +The raster backend draws to a block of memory. This memory can be +managed by Skia or by the client. + +The recommended way of creating a canvas for the Raster and Ganesh +backends is to use a `SkSurface`, which is an object that manages +the memory into which the canvas commands are drawn. + + + + #include "SkData.h" + #include "SkImage.h" + #include "SkStream.h" + #include "SkSurface.h" + void raster(int width, int height, + void (*draw)(SkCanvas*), + const char* path) { + sk_sp rasterSurface = + SkSurface::MakeRasterN32Premul(width, height); + SkCanvas* rasterCanvas = rasterSurface->getCanvas(); + draw(rasterCanvas); + sk_sp img(rasterSurface->makeImageSnapshot()); + if (!img) { return; } + sk_sp png(img->encode()); + if (!png) { return; } + SkFILEWStream out(path); + (void)out.write(png->data(), png->size()); + } + +Alternatively, we could have specified the memory for the surface +explicitly, instead of asking Skia to manage it. + + + + #include + #include "SkSurface.h" + std::vector raster_direct(int width, int height, + void (*draw)(SkCanvas*)) { + SkImageInfo info = SkImageInfo::MakeN32Premul(width, height); + size_t rowBytes = info.minRowBytes(); + size_t size = info.getSafeSize(rowBytes); + std::vector pixelMemory(size); // allocate memory + sk_sp surface = + SkSurface::MakeRasterDirect( + info, &pixelMemory[0], rowBytes); + SkCanvas* canvas = surface->getCanvas(); + draw(canvas); + return pixelMemory; + } + + +GPU +------ + +GPU Surfaces must have a `GrContext` object which manages the +GPU context, and related caches for textures and fonts. GrContexts +are matched one to one with OpenGL contexts or Vulkan devices. That is, all +SkSurfaces that will be rendered to using the same OpenGL context or Vulkan +device should share a GrContext. Skia does not create a OpenGL context or Vulkan +device for you. In OpenGL mode it also assumes that the correct OpenGL context +has been made current to the current thread when Skia calls are made. + + + + #include "GrContext.h" + #include "gl/GrGLInterface.h" + #include "SkData.h" + #include "SkImage.h" + #include "SkStream.h" + #include "SkSurface.h" + + void gl_example(int width, int height, void (*draw)(SkCanvas*), const char* path) { + // You've already created your OpenGL context and bound it. + const GrGLInterface* interface = nullptr; + // Leaving interface as null makes Skia extract pointers to OpenGL functions for the current + // context in a platform-specific way. Alternatively, you may create your own GrGLInterface and + // initialize it however you like to attach to an alternate OpenGL implementation or intercept + // Skia's OpenGL calls. + sk_sp context = GrContext::MakeGL(interface); + SkImageInfo info = SkImageInfo:: MakeN32Premul(width, height); + sk_sp gpuSurface( + SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, info)); + if (!gpuSurface) { + SkDebugf("SkSurface::MakeRenderTarget returned null\n"); + return; + } + SkCanvas* gpuCanvas = gpuSurface->getCanvas(); + draw(gpuCanvas); + sk_sp img(gpuSurface->makeImageSnapshot()); + if (!img) { return; } + sk_sp png(img->encode()); + if (!png) { return; } + SkFILEWStream out(path); + (void)out.write(png->data(), png->size()); + } + + +SkPDF +----- + +The SkPDF backend uses `SkDocument` instead of `SkSurface`, since +a document must include multiple pages. + + + + #include "SkDocument.h" + #include "SkStream.h" + void skpdf(int width, int height, + void (*draw)(SkCanvas*), + const char* path) { + SkFILEWStream pdfStream(path); + sk_sp pdfDoc = SkDocument::MakePDF(&pdfStream); + SkCanvas* pdfCanvas = pdfDoc->beginPage(SkIntToScalar(width), + SkIntToScalar(height)); + draw(pdfCanvas); + pdfDoc->close(); + } + + +SkPicture +--------- + +The SkPicture backend uses SkPictureRecorder instead of SkSurface. + + + + #include "SkPictureRecorder.h" + #include "SkPicture.h" + #include "SkStream.h" + void picture(int width, int height, + void (*draw)(SkCanvas*), + const char* path) { + SkPictureRecorder recorder; + SkCanvas* recordingCanvas = recorder.beginRecording(SkIntToScalar(width), + SkIntToScalar(height)); + draw(recordingCanvas); + sk_sp picture = recorder.finishRecordingAsPicture(); + SkFILEWStream skpStream(path); + // Open SKP files with `SampleApp --picture SKP_FILE` + picture->serialize(&skpStream); + } + + +NullCanvas +---------- + +The null canvas is a canvas that ignores all drawing commands and does +nothing. + + + + #include "SkNullCanvas.h" + void null_canvas_example(int, int, void (*draw)(SkCanvas*), const char*) { + std::unique_ptr nullCanvas = SkMakeNullCanvas(); + draw(nullCanvas.get()); // NoOp + } + + +SkXPS +----- + +The (*still experimental*) SkXPS canvas writes into an XPS document. + + + + #include "SkDocument.h" + #include "SkStream.h" + #ifdef SK_BUILD_FOR_WIN + void skxps(IXpsOMObjectFactory* factory; + int width, int height, + void (*draw)(SkCanvas*), + const char* path) { + SkFILEWStream xpsStream(path); + sk_sp xpsDoc = SkDocument::MakeXPS(&pdfStream, factory); + SkCanvas* xpsCanvas = xpsDoc->beginPage(SkIntToScalar(width), + SkIntToScalar(height)); + draw(xpsCanvas); + xpsDoc->close(); + } + #endif + + +SkSVG +----- + +The (*still experimental*) SkSVG canvas writes into an SVG document. + + + + #include "SkStream.h" + #include "SkSVGCanvas.h" + #include "SkXMLWriter.h" + void sksvg(int width, int height, + void (*draw)(SkCanvas*), + const char* path) { + SkFILEWStream svgStream(path); + std::unique_ptr xmlWriter( + new SkXMLStreamWriter(&svgStream)); + SkRect bounds = SkRect::MakeIWH(width, height); + std::unique_ptr svgCanvas = + SkSVGCanvas::Make(bounds, xmlWriter.get()); + draw(svgCanvas.get()); + } + + +Example +------- + +To try this code out, make a [new unit test using instructions +here](/dev/testing/tests) and wrap these funtions together: + + + + #include "SkCanvas.h" + #include "SkPath.h" + #include "Test.h" + void example(SkCanvas* canvas) { + const SkScalar scale = 256.0f; + const SkScalar R = 0.45f * scale; + const SkScalar TAU = 6.2831853f; + SkPath path; + for (int i = 0; i < 5; ++i) { + SkScalar theta = 2 * i * TAU / 5; + if (i == 0) { + path.moveTo(R * cos(theta), R * sin(theta)); + } else { + path.lineTo(R * cos(theta), R * sin(theta)); + } + } + path.close(); + SkPaint p; + p.setAntiAlias(true); + canvas->clear(SK_ColorWHITE); + canvas->translate(0.5f * scale, 0.5f * scale); + canvas->drawPath(path, p); + } + DEF_TEST(FourBackends, r) { + raster( 256, 256, example, "out_raster.png" ); + gl_example( 256, 256, example, "out_gpu.png" ); + skpdf( 256, 256, example, "out_skpdf.pdf" ); + picture( 256, 256, example, "out_picture.skp"); + } diff --git a/site/user/api/index.md b/site/user/api/index.md index 3d02eddc7f..008f9a15d1 100644 --- a/site/user/api/index.md +++ b/site/user/api/index.md @@ -24,14 +24,17 @@ attributes of the drawing are controlled by the paint. Using the SkCanvas API: -1. **[SkCanvas](/user/api/skcanvas)** - the drawing context. -2. **[SkPaint](/user/api/skpaint)** - color, stroke, font, effects -3. **[SkRect](/user/api/skrect)** - rectangles -4. **[SkRegion](/user/api/skregion)** - set operations with rectangles and paths +1. **[SkCanvas Overview](/user/api/skcanvas_overview)** - the drawing context. +2. **[Creating SkCanvas Objects](/user/api/creating_skcanvas)** +3. **[SkPaint Overview](/user/api/skpaint_overview)** - color, stroke, font, effects +4. **[SkRect Overview](/user/api/skrect_overview)** - rectangles +5. **[SkRegion Overview](/user/api/skregion_overview)** - set operations with rectangles and paths -Appendix: +Reference: -1. **[Creating SkCanvas Objects](/user/api/canvas)** +1. **[SkCanvas Reference](/user/api/SkCanvas_Reference)** - the drawing context. +2. **[SkPaint Reference](/user/api/SkPaint_Reference)** - color, stroke, font, effects +3. **[SkPath Reference](/user/api/SkPath_Reference)** - paths Autogenerated Doxygen Documentaion ---------------------------------- diff --git a/site/user/api/skcanvas.md b/site/user/api/skcanvas.md deleted file mode 100644 index a1e3428a32..0000000000 --- a/site/user/api/skcanvas.md +++ /dev/null @@ -1,70 +0,0 @@ -SkCanvas -======== - -*The drawing context* - - - -Preview -------- - -Here is an example of a set of drawing commands to draw a filled -heptagram. This function can be cut and pasted into -[fiddle.skia.org](https://fiddle.skia.org/). - - - -Details -------- - -SkCanvas is the drawing context for Skia. It knows where to direct the -drawing (i.e. where the screen of offscreen pixels are), and maintains -a stack of matrices and clips. Note however, that unlike similar -contexts in other APIs like postscript, cairo, or awt, Skia does not -store any other drawing attributes in the context (e.g. color, pen -size). Rather, these are specified explicitly in each draw call, via a -SkPaint. - - - -The code above will draw a rectangle rotated by 45 degrees. Exactly -what color and style the rect will be drawn in is described by the -paint, not the canvas. - -Check out more detailed info on [creating a SkCanvas object](canvas). - -To begin with, we might want to erase the entire canvas. We can do -this by drawing an enormous rectangle, but there are easier ways to do -it. - - - - void draw(SkCanvas* canvas) { - SkPaint paint; - paint.setColor(SK_ColorWHITE); - canvas->drawPaint(paint); - } - -This fills the entire canvas (though respecting the current clip of -course) with whatever color or shader (and xfermode) is specified by -the paint. If there is a shader in the paint, then it will respect the -current matrix on the canvas as well (see SkShader). If you just want -to draw a color (with an optional xfermode), you can just call -drawColor(), and save yourself having to allocate a paint. - - - - void draw(SkCanvas* canvas) { - canvas->drawColor(SK_ColorWHITE); - } - -All of the other draw APIs are similar, each one ending with a paint -parameter. - - - -In some of the calls, we pass a pointer, rather than a reference, to -the paint. In those instances, the paint parameter may be null. In all -other cases the paint parameter is required. - -Next: [SkPaint](/user/api/skpaint) diff --git a/site/user/api/skcanvas_overivew.md b/site/user/api/skcanvas_overivew.md new file mode 100644 index 0000000000..250b561d94 --- /dev/null +++ b/site/user/api/skcanvas_overivew.md @@ -0,0 +1,70 @@ +SkCanvas Overview +======== + +*The drawing context* + + + +Preview +------- + +Here is an example of a set of drawing commands to draw a filled +heptagram. This function can be cut and pasted into +[fiddle.skia.org](https://fiddle.skia.org/). + + + +Details +------- + +SkCanvas is the drawing context for Skia. It knows where to direct the +drawing (i.e. where the screen of offscreen pixels are), and maintains +a stack of matrices and clips. Note however, that unlike similar +contexts in other APIs like postscript, cairo, or awt, Skia does not +store any other drawing attributes in the context (e.g. color, pen +size). Rather, these are specified explicitly in each draw call, via a +SkPaint. + + + +The code above will draw a rectangle rotated by 45 degrees. Exactly +what color and style the rect will be drawn in is described by the +paint, not the canvas. + +Check out more detailed info on [creating a SkCanvas object](canvas). + +To begin with, we might want to erase the entire canvas. We can do +this by drawing an enormous rectangle, but there are easier ways to do +it. + + + + void draw(SkCanvas* canvas) { + SkPaint paint; + paint.setColor(SK_ColorWHITE); + canvas->drawPaint(paint); + } + +This fills the entire canvas (though respecting the current clip of +course) with whatever color or shader (and xfermode) is specified by +the paint. If there is a shader in the paint, then it will respect the +current matrix on the canvas as well (see SkShader). If you just want +to draw a color (with an optional xfermode), you can just call +drawColor(), and save yourself having to allocate a paint. + + + + void draw(SkCanvas* canvas) { + canvas->drawColor(SK_ColorWHITE); + } + +All of the other draw APIs are similar, each one ending with a paint +parameter. + + + +In some of the calls, we pass a pointer, rather than a reference, to +the paint. In those instances, the paint parameter may be null. In all +other cases the paint parameter is required. + +Next: [SkPaint](/user/api/skpaint) diff --git a/site/user/api/skmatrix.md b/site/user/api/skmatrix.md deleted file mode 100644 index 3048cdc19f..0000000000 --- a/site/user/api/skmatrix.md +++ /dev/null @@ -1,12 +0,0 @@ -SkMatrix -======== - -*3x3 transforms* - - - -Skia is a 2D graphics engine, but it supports a full 3x3 -transformation matrix. This allow it to draw anything (bitmaps, text, -rectangles, paths) in perspective. SkCamera is a helper class that -models a camera in 3D, and can be used to generate the proper matrix -for a given 3D view of the plane. diff --git a/site/user/api/skmatrix_overivew.md b/site/user/api/skmatrix_overivew.md new file mode 100644 index 0000000000..5dce28cc62 --- /dev/null +++ b/site/user/api/skmatrix_overivew.md @@ -0,0 +1,12 @@ +SkMatrix Overview +======== + +*3x3 transforms* + + + +Skia is a 2D graphics engine, but it supports a full 3x3 +transformation matrix. This allow it to draw anything (bitmaps, text, +rectangles, paths) in perspective. SkCamera is a helper class that +models a camera in 3D, and can be used to generate the proper matrix +for a given 3D view of the plane. diff --git a/site/user/api/skpaint.md b/site/user/api/skpaint.md deleted file mode 100644 index 0d404cacc8..0000000000 --- a/site/user/api/skpaint.md +++ /dev/null @@ -1,207 +0,0 @@ -SkPaint -======= - - -*color, stroke, font, effects* - -
- -
- - -Anytime you draw something in Skia, and want to specify what color it -is, or how it blends with the background, or what style or font to -draw it in, you specify those attributes in a paint. - -Unlike `SkCanvas`, paints do not maintain an internal stack of state -(i.e. there is no save/restore on a paint). However, paints are -relatively light-weight, so the client may create and maintain any -number of paint objects, each set up for a particular use. Factoring -all of these color and stylistic attributes out of the canvas state, -and into (multiple) paint objects, allows canvas' save/restore to be -that much more efficient, as all they have to do is maintain the stack -of matrix and clip settings. - - - -This shows three different paints, each set up to draw in a different -style. Now the caller can intermix these paints freely, either using -them as is, or modifying them as the drawing proceeds. - - - -Beyond simple attributes such as color, strokes, and text values, -paints support effects. These are subclasses of different aspects of -the drawing pipeline, that when referenced by a paint (each of them is -reference-counted), are called to override some part of the drawing -pipeline. - -For example, to draw using a gradient instead of a single color, -assign a SkShader to the paint. - - - -Now, anything drawn with that paint will be drawn with the gradient -specified in the call to `MakeLinear()`. The shader object that is -returned is reference-counted. Whenever any effects object, like a -shader, is assigned to a paint, its reference-count is increased by -the paint. To balance this, the caller in the above example calls -`unref()` on the shader once it has assigned it to the paint. Now the -paint is the only "owner" of that shader, and it will automatically -call `unref()` on the shader when either the paint goes out of scope, or -if another shader (or null) is assigned to it. - -There are 6 types of effects that can be assigned to a paint: - -* **SkPathEffect** - modifications to the geometry (path) before it - generates an alpha mask (e.g. dashing) -* **SkRasterizer** - composing custom mask layers (e.g. shadows) -* **SkMaskFilter** - modifications to the alpha mask before it is - colorized and drawn (e.g. blur) -* **SkShader** - e.g. gradients (linear, radial, sweep), bitmap patterns - (clamp, repeat, mirror) -* **SkColorFilter** - modify the source color(s) before applying the - xfermode (e.g. color matrix) -* **SkXfermode** - e.g. porter-duff transfermodes, blend modes - -Paints also hold a reference to a SkTypeface. The typeface represents -a specific font style, to be used for measuring and drawing -text. Speaking of which, paints are used not only for drawing text, -but also for measuring it. - - - - paint.measureText(...); - paint.getTextBounds(...); - paint.textToGlyphs(...); - paint.getFontMetrics(...); - - - -SkXfermode ----------- - -The following example demonstrates all of the Skia's standard transfer -modes. In this example the source is a solid magenta color with a -horizontal alpha gradient and the destination is a solid cyan color -with a vertical alpha gradient. - - - - - -SkShader --------- - -Several shaders are defined (besides the linear gradient already mentioned): - -* Bitmap Shader - - - -* Radial Gradient Shader - - - -* Two-Point Conical Gradient Shader - - - - -* Sweep Gradient Shader - - - -* Fractal Perlin Noise Shader - - - -* Turbulence Perlin Noise Shader - - - -* Compose Shader - - - - - - -SkMaskFilter ------------- - -* Blur Mask Filter - - - - - - -SkColorFilter -------------- - -* Color Matrix Color Filter - - - -* Color Table Color Filter - - - - - -SkPathEffect ------------- - -* SkPath2DPathEffect: Stamp the specified path to fill the shape, - using the matrix to define the latice. - - - -* SkLine2DPathEffect: a special case of SkPath2DPathEffect where the - path is a straight line to be stroked, not a path to be filled. - - - -* SkPath1DPathEffect: create dash-like effects by replicating the specified path along the drawn path. - - - -* SkArcToPathEffect - - The following few examples use this function: - - - -* SkCornerPathEffect: a path effect that can turn sharp corners into - various treatments (e.g. rounded corners). - - - -* SkDashPathEffect: a path effect that implements dashing. - - - -* SkDiscretePathEffect: This path effect chops a path into discrete - segments, and randomly displaces them. - - - -* SkComposePathEffect: a pathEffect whose effect is to apply - first the inner pathEffect and the the outer pathEffect (i.e. - outer(inner(path))). - - - -* SkSumPathEffect: a pathEffect whose effect is to apply two effects, - in sequence (i.e. first(path) + second(path)). - - - diff --git a/site/user/api/skpaint_overview.md b/site/user/api/skpaint_overview.md new file mode 100644 index 0000000000..df89812bb5 --- /dev/null +++ b/site/user/api/skpaint_overview.md @@ -0,0 +1,207 @@ +SkPaint Overview +======= + + +*color, stroke, font, effects* + +
+ +
+ + +Anytime you draw something in Skia, and want to specify what color it +is, or how it blends with the background, or what style or font to +draw it in, you specify those attributes in a paint. + +Unlike `SkCanvas`, paints do not maintain an internal stack of state +(i.e. there is no save/restore on a paint). However, paints are +relatively light-weight, so the client may create and maintain any +number of paint objects, each set up for a particular use. Factoring +all of these color and stylistic attributes out of the canvas state, +and into (multiple) paint objects, allows canvas' save/restore to be +that much more efficient, as all they have to do is maintain the stack +of matrix and clip settings. + + + +This shows three different paints, each set up to draw in a different +style. Now the caller can intermix these paints freely, either using +them as is, or modifying them as the drawing proceeds. + + + +Beyond simple attributes such as color, strokes, and text values, +paints support effects. These are subclasses of different aspects of +the drawing pipeline, that when referenced by a paint (each of them is +reference-counted), are called to override some part of the drawing +pipeline. + +For example, to draw using a gradient instead of a single color, +assign a SkShader to the paint. + + + +Now, anything drawn with that paint will be drawn with the gradient +specified in the call to `MakeLinear()`. The shader object that is +returned is reference-counted. Whenever any effects object, like a +shader, is assigned to a paint, its reference-count is increased by +the paint. To balance this, the caller in the above example calls +`unref()` on the shader once it has assigned it to the paint. Now the +paint is the only "owner" of that shader, and it will automatically +call `unref()` on the shader when either the paint goes out of scope, or +if another shader (or null) is assigned to it. + +There are 6 types of effects that can be assigned to a paint: + +* **SkPathEffect** - modifications to the geometry (path) before it + generates an alpha mask (e.g. dashing) +* **SkRasterizer** - composing custom mask layers (e.g. shadows) +* **SkMaskFilter** - modifications to the alpha mask before it is + colorized and drawn (e.g. blur) +* **SkShader** - e.g. gradients (linear, radial, sweep), bitmap patterns + (clamp, repeat, mirror) +* **SkColorFilter** - modify the source color(s) before applying the + xfermode (e.g. color matrix) +* **SkXfermode** - e.g. porter-duff transfermodes, blend modes + +Paints also hold a reference to a SkTypeface. The typeface represents +a specific font style, to be used for measuring and drawing +text. Speaking of which, paints are used not only for drawing text, +but also for measuring it. + + + + paint.measureText(...); + paint.getTextBounds(...); + paint.textToGlyphs(...); + paint.getFontMetrics(...); + + + +SkXfermode +---------- + +The following example demonstrates all of the Skia's standard transfer +modes. In this example the source is a solid magenta color with a +horizontal alpha gradient and the destination is a solid cyan color +with a vertical alpha gradient. + + + + + +SkShader +-------- + +Several shaders are defined (besides the linear gradient already mentioned): + +* Bitmap Shader + + + +* Radial Gradient Shader + + + +* Two-Point Conical Gradient Shader + + + + +* Sweep Gradient Shader + + + +* Fractal Perlin Noise Shader + + + +* Turbulence Perlin Noise Shader + + + +* Compose Shader + + + + + + +SkMaskFilter +------------ + +* Blur Mask Filter + + + + + + +SkColorFilter +------------- + +* Color Matrix Color Filter + + + +* Color Table Color Filter + + + + + +SkPathEffect +------------ + +* SkPath2DPathEffect: Stamp the specified path to fill the shape, + using the matrix to define the latice. + + + +* SkLine2DPathEffect: a special case of SkPath2DPathEffect where the + path is a straight line to be stroked, not a path to be filled. + + + +* SkPath1DPathEffect: create dash-like effects by replicating the specified path along the drawn path. + + + +* SkArcToPathEffect + + The following few examples use this function: + + + +* SkCornerPathEffect: a path effect that can turn sharp corners into + various treatments (e.g. rounded corners). + + + +* SkDashPathEffect: a path effect that implements dashing. + + + +* SkDiscretePathEffect: This path effect chops a path into discrete + segments, and randomly displaces them. + + + +* SkComposePathEffect: a pathEffect whose effect is to apply + first the inner pathEffect and the the outer pathEffect (i.e. + outer(inner(path))). + + + +* SkSumPathEffect: a pathEffect whose effect is to apply two effects, + in sequence (i.e. first(path) + second(path)). + + + diff --git a/site/user/api/skrect.md b/site/user/api/skrect.md deleted file mode 100644 index c2ebef1d0f..0000000000 --- a/site/user/api/skrect.md +++ /dev/null @@ -1,73 +0,0 @@ -SkRect -====== - -*Rectangles* - - - -SkRect is basic to many drawing and measuring operations. It can be -drawn using canvas.drawRect(), but it is also used to return the -bounds of objects like paths and text characters. It is specified -using SkScalar values. - -SkIRect is the integer counter part to SkRect, but is specified using -32bit integers. - - - - struct SkRect { - SkScalar fLeft; - SkScalar fTop; - SkScalar fRight; - SkScalar fBottom; - // methods - }; - - SkRect rect = SkRect::MakeLTRB(left, top, right, bottom); - -SkRect has the usual getters, to return width(), height(), centerX(), -etc. It also has methods to compute unions and intersections between -rectangles. - -Converting between SkRect and SkIRect is asymetric. Short of overflow -issues when SkScalar is an int, converting from SkIRect to SkRect is -straight forward: - - - - SkRect::set(const SkIRect&); - -However, convert from SkRect to SkIRect needs to know how to go from -fractional values to integers. - - - - SkRect::round(SkIRect*) const; // Round each coordinate. - SkRect::roundOut(SkIRect*) const; // Apply floor to left/top, - // and ceil to right/bottom. - -In Skia, rectangle coordinates describe the boundary of what is drawn, -such that an empty rectangle encloses zero pixels: - -bool SkRect::isEmpty() const { return fLeft >= fRight || fTop >= fBottom; } - - - - SkScalar SkRect::width() const { return fRight - fLeft; } - - SkScalar SkRect::height() const { return fBottom - fTop; } - - bool SkRect::contains(SkScalar x, SkScalar y) const { - return fLeft <= x && x < fRight && fTop <= y && y < fBottom; - } - -Thus, to draw a single pixel (assuming no matrix on the canvas), the -rectangle should be initialized as follows: - - - - SkRect r = SkRect::MakeXYWH(x, y, SkIntToScalar(1), SkIntToScalar(1)); - -The same conventions hold for the integer counterpart: SkIRect. This -also dovetails with SkRegion, which has the same model for set -membership, and which uses SkIRect. diff --git a/site/user/api/skrect_overivew.md b/site/user/api/skrect_overivew.md new file mode 100644 index 0000000000..757c751498 --- /dev/null +++ b/site/user/api/skrect_overivew.md @@ -0,0 +1,73 @@ +SkRect Overview +====== + +*Rectangles* + + + +SkRect is basic to many drawing and measuring operations. It can be +drawn using canvas.drawRect(), but it is also used to return the +bounds of objects like paths and text characters. It is specified +using SkScalar values. + +SkIRect is the integer counter part to SkRect, but is specified using +32bit integers. + + + + struct SkRect { + SkScalar fLeft; + SkScalar fTop; + SkScalar fRight; + SkScalar fBottom; + // methods + }; + + SkRect rect = SkRect::MakeLTRB(left, top, right, bottom); + +SkRect has the usual getters, to return width(), height(), centerX(), +etc. It also has methods to compute unions and intersections between +rectangles. + +Converting between SkRect and SkIRect is asymetric. Short of overflow +issues when SkScalar is an int, converting from SkIRect to SkRect is +straight forward: + + + + SkRect::set(const SkIRect&); + +However, convert from SkRect to SkIRect needs to know how to go from +fractional values to integers. + + + + SkRect::round(SkIRect*) const; // Round each coordinate. + SkRect::roundOut(SkIRect*) const; // Apply floor to left/top, + // and ceil to right/bottom. + +In Skia, rectangle coordinates describe the boundary of what is drawn, +such that an empty rectangle encloses zero pixels: + +bool SkRect::isEmpty() const { return fLeft >= fRight || fTop >= fBottom; } + + + + SkScalar SkRect::width() const { return fRight - fLeft; } + + SkScalar SkRect::height() const { return fBottom - fTop; } + + bool SkRect::contains(SkScalar x, SkScalar y) const { + return fLeft <= x && x < fRight && fTop <= y && y < fBottom; + } + +Thus, to draw a single pixel (assuming no matrix on the canvas), the +rectangle should be initialized as follows: + + + + SkRect r = SkRect::MakeXYWH(x, y, SkIntToScalar(1), SkIntToScalar(1)); + +The same conventions hold for the integer counterpart: SkIRect. This +also dovetails with SkRegion, which has the same model for set +membership, and which uses SkIRect. diff --git a/site/user/api/skregion.md b/site/user/api/skregion.md deleted file mode 100644 index f4f46c951b..0000000000 --- a/site/user/api/skregion.md +++ /dev/null @@ -1,111 +0,0 @@ -SkRegion -======== - -*Regions - set operations with rectangles* - - - -Regions are a highly compressed way to represent (integer) areas. Skia -uses them to represent (internally) the current clip on the -canvas. Regions take their inspiration from the data type with the -same name on the original Macintosh (thank you Bill). - -Regions are opaque structures, but they can be queried via -iterators. Best of all, they can be combined with other regions and -with rectangles (which can be thought of as "simple" regions. If you -remember Set operations from math class (intersection, union, -difference, etc.), then you're all ready to use regions. - - - - bool SkRegion::isEmpty(); - bool SkRegion::isRect(); - bool SkRegion::isComplex(); - -Regions can be classified into one of three types: empty, rectangular, -or complex. - -Empty regions are just that, empty. All empty regions are equal (using -operator==). Compare this to rectangles (SkRect or SkIRect). Any -rectangle with fLeft >= fRight or fTop >= fBottom is consider empty, -but clearly there are different empty rectangles that are not equal. - - - - SkRect a = { 0, 0, 0, 0 }; - SkRect b = { 1, 1, 1, 1 }; - -Both a and b are empty, but they are definitely not equal to each -other. However, with regions, all empty regions are equal. If you -query its bounds, you will always get { 0, 0, 0, 0 }. Even if you -translate it, it will still be all zeros. - - - - - - SkRegion a, b; // regions default to empty - assert(a == b); - a.offset(10, 20); - assert(a == b); - assert(a.getBounds() == { 0, 0, 0, 0 }); // not legal C++, but you get the point - assert(b.getBounds() == { 0, 0, 0, 0 }); - -To initialize a region to something more interesting, use one of the -set() methods - - - - SkRegion a, b; - a.setRect(10, 10, 50, 50); - b.setRect(rect); // see SkIRect - c.setPath(path); // see SkPath - -This is the first step that SkCanvas performs when one of its -clip...() methods are called. The clip data is first transformed into -device coordinates (see SkMatrix), and then a region is build from the -data (either a rect or a path). The final step is to combine this new -region with the existing clip using the specified operator. - - - - enum Op { - kUnion_Op, - kIntersect_Op, - kDifference_Op, - kXor_Op, - kReverseDifference_Op, - kReplace_Op - }; - -By default, intersect op is used when a clip call is made, but the -other operators are equally valid. - - - - // returns true if the resulting clip is non-empty (i.e. drawing can - // still occur) - bool SkCanvas::clipRect(const SkRect& rect, SkRegion::Op op) { - SkRegion rgn; - - // peek at the CTM (current transformation matrix on the canvas) - const SkMatrix& m = this->getTotalMatrix(); - - if (m.rectStaysRect()) { // check if a transformed rect can be - // represented as another rect - - SkRect deviceRect; - m.mapRect(&deviceRect, rect); - SkIRect intRect; - deviceRect.round(&intRect); - rgn.setRect(intRect); - } else { // matrix rotates or skew (or is perspective) - SkPath path; - path.addRect(rect); - path.transform(m); - rgn.setPath(path); - } - - // now combine the new region with the current one, using the specified *op* - return fCurrentClip.op(rgn, op); - } diff --git a/site/user/api/skregion_overview.md b/site/user/api/skregion_overview.md new file mode 100644 index 0000000000..9d7e57170b --- /dev/null +++ b/site/user/api/skregion_overview.md @@ -0,0 +1,111 @@ +SkRegion Overview +======== + +*Regions - set operations with rectangles* + + + +Regions are a highly compressed way to represent (integer) areas. Skia +uses them to represent (internally) the current clip on the +canvas. Regions take their inspiration from the data type with the +same name on the original Macintosh (thank you Bill). + +Regions are opaque structures, but they can be queried via +iterators. Best of all, they can be combined with other regions and +with rectangles (which can be thought of as "simple" regions. If you +remember Set operations from math class (intersection, union, +difference, etc.), then you're all ready to use regions. + + + + bool SkRegion::isEmpty(); + bool SkRegion::isRect(); + bool SkRegion::isComplex(); + +Regions can be classified into one of three types: empty, rectangular, +or complex. + +Empty regions are just that, empty. All empty regions are equal (using +operator==). Compare this to rectangles (SkRect or SkIRect). Any +rectangle with fLeft >= fRight or fTop >= fBottom is consider empty, +but clearly there are different empty rectangles that are not equal. + + + + SkRect a = { 0, 0, 0, 0 }; + SkRect b = { 1, 1, 1, 1 }; + +Both a and b are empty, but they are definitely not equal to each +other. However, with regions, all empty regions are equal. If you +query its bounds, you will always get { 0, 0, 0, 0 }. Even if you +translate it, it will still be all zeros. + + + + + + SkRegion a, b; // regions default to empty + assert(a == b); + a.offset(10, 20); + assert(a == b); + assert(a.getBounds() == { 0, 0, 0, 0 }); // not legal C++, but you get the point + assert(b.getBounds() == { 0, 0, 0, 0 }); + +To initialize a region to something more interesting, use one of the +set() methods + + + + SkRegion a, b; + a.setRect(10, 10, 50, 50); + b.setRect(rect); // see SkIRect + c.setPath(path); // see SkPath + +This is the first step that SkCanvas performs when one of its +clip...() methods are called. The clip data is first transformed into +device coordinates (see SkMatrix), and then a region is build from the +data (either a rect or a path). The final step is to combine this new +region with the existing clip using the specified operator. + + + + enum Op { + kUnion_Op, + kIntersect_Op, + kDifference_Op, + kXor_Op, + kReverseDifference_Op, + kReplace_Op + }; + +By default, intersect op is used when a clip call is made, but the +other operators are equally valid. + + + + // returns true if the resulting clip is non-empty (i.e. drawing can + // still occur) + bool SkCanvas::clipRect(const SkRect& rect, SkRegion::Op op) { + SkRegion rgn; + + // peek at the CTM (current transformation matrix on the canvas) + const SkMatrix& m = this->getTotalMatrix(); + + if (m.rectStaysRect()) { // check if a transformed rect can be + // represented as another rect + + SkRect deviceRect; + m.mapRect(&deviceRect, rect); + SkIRect intRect; + deviceRect.round(&intRect); + rgn.setRect(intRect); + } else { // matrix rotates or skew (or is perspective) + SkPath path; + path.addRect(rect); + path.transform(m); + rgn.setPath(path); + } + + // now combine the new region with the current one, using the specified *op* + return fCurrentClip.op(rgn, op); + } diff --git a/site/user/api/undocumented.md b/site/user/api/undocumented.md new file mode 100644 index 0000000000..2a50f14246 --- /dev/null +++ b/site/user/api/undocumented.md @@ -0,0 +1,638 @@ +(to be documented) +=== + +# Glyph + +# Curve + +# Document + +# Class SkDocument + + +## beginPage + +
+SkCanvas* beginPage(SkScalar width, SkScalar height,
+                    const SkRect* content = NULL)
+
+ +--- + +## PDF + +# Arc + +# Rect + +# Struct SkRect + + +## MakeEmpty + +
+static constexpr SkRect SK_WARN_UNUSED_RESULT MakeEmpty()
+
+ +--- + + +## dump + +
+void dump() const
+
+ +--- + + +## dumpHex + +
+void dumpHex() const
+
+ +--- + +# Line + +# Region + +# Class SkRegion + +# Device + +# Class SkBaseDevice + +# Vector + +# Struct SkVector + +# Point + +# Struct SkPoint + + +## equalsWithinTolerance + +
+bool equalsWithinTolerance(const SkPoint& p) const
+
+ +--- + +## Array + +# Patch + +# Typeface + +# Class SkTypeface + +# Dump Canvas + +# Class SkDumpCanvas + +# BBH Factory + +# Class SkBBHFactory + +# Bitmap + +# Class SkBitmap + +## Row Bytes + +# Blend Mode + +## Enum SkBlendMode + +### Constants + + + + + + + + + + + + +
SkBlendMode::kSrc 1
SkBlendMode::kSrcOver 3
SkBlendMode::kPlus 12
+ +# Circle + +# Clip Op + +## Enum SkClipOp + +### Constants + + + + + + + + + +
SkClipOp::kDifference 0
SkClipOp::kIntersect 1
+ +# Color + + +## SkColorGetA + +
+int SkColorGetA(color)
+
+ +--- + + +## SkColorGetR + +
+int SkColorGetR(color)
+
+ +--- + + +## SkColorGetG + +
+int SkColorGetG(color)
+
+ +--- + + +## SkColorGetB + +
+int SkColorGetB(color)
+
+ +--- + + +## SkColorSetARGB + +
+int SkColorSetARGB(a, r, g, b)
+
+ +--- + +### Constants + + + + + + + + + + + + + + + + + +
SK_ColorBLACK 0xFF000000
SK_ColorBLUE 0xFF0000FF
SK_ColorGREEN 0xFF00FF00
SK_ColorRED 0xFFFF0000
SK_ColorWHITE 0xFFFFFFFF
+ +## Alpha + +## RGB + +## Red + +## Blue + +## Green + +## ARGB + +## RBG + +## RGB-565 + +# Color Filter + +# Class SkColorFilter + +# Color Space + +# Data + +# Draw Filter + +# Class SkDrawFilter + +# Draw Looper + +# Class SkDrawLooper + +# Drawable + +# Class SkDrawable + + +## draw + +
+void draw(SkCanvas*, const SkMatrix* = NULL)
+
+ +--- + +# Raster Handle Allocator + +# Class SkRasterHandleAllocator + +# Struct SkRasterHandleAllocator::Rec + + +## MakeCanvas + +
+static std::unique_ptr 
+                                            MakeCanvas(std::unique_ptr,
+                                            const SkImageInfo&,
+                                            const Rec* rec = nullptr)
+
+ +--- + +# Filter Quality + +## Enum SkFilterQuality + +### Constants + + + + + + + + + + + + + + + +
kNone_SkFilterQuality 0
kLow_SkFilterQuality 1
kMedium_SkFilterQuality 2
kHigh_SkFilterQuality 3
+ +# Font + +## Advance + +## Engine + +# Oval + +# Font Manager + +# Image + +## Alpha Type + +## Enum SkAlphaType + +### Constants + + + + + + +
kPremul_SkAlphaType 2
+ +## Color Type + +## Enum SkColorType + +### Constants + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
kUnknown_SkColorType 0
kAlpha_8_SkColorType 1
kRGB_565_SkColorType 2
kARGB_4444_SkColorType 3
kRGBA_8888_SkColorType 4
kBGRA_8888_SkColorType 5
kIndex_8_SkColorType 6
kGray_8_SkColorType 7
kRGBA_F16_SkColorType 8
+ +### Constants + + + + + + +
kN32_SkColorType 4
+ +## Info + +# Struct SkImageInfo + + +## SkImageInfo + +
+SkImageInfo()
+
+ +--- + +# Class SkImage + + +## makeShader + +
+sk_sp makeShader(SkShader::TileMode, SkShader::TileMode,
+                           const SkMatrix* localMatrix = nullptr) const
+
+ +--- + +# Image Filter + +## Scaling + +# Class SkImageFilter + +# Image Scaling + +# IRect + +# Struct SkIRect + +# Mask + +# Mask Alpha + +# Mask Filter + +# Class SkMaskFilter + +# Matrix + +# Struct SkMatrix + +# Nine Patch + +# Number Types + +### Constants + + + + + + + + + + + + + + +
SK_ScalarMax to be written
SK_ScalarInfinity to be written
SK_ScalarNegativeInfinity to be written
SK_ScalarNaN to be written
+ +# Paint Defaults + +### Constants + + + + + + + + + + + + + + +
SkPaintDefaults_Flags 0
SkPaintDefaults_Hinting 2
SkPaintDefaults_TextSize 12
SkPaintDefaults_MiterLimit 4
+ +# Path Effect + +# Class SkPathEffect + +# Path Measure + +# Class SkPathMeasure + + +## dump + +
+void dump() const
+
+ +--- + +# PathOps + + +## Op + +
+bool SK_API Op(const SkPath& one, const SkPath& two, SkPathOp op, SkPath* result)
+
+ +--- + +# Picture + +## Recorder + +# Class SkPictureRecorder + + +## beginRecording + +
+SkCanvas* beginRecording(const SkRect& bounds, SkBBHFactory* bbhFactory = NULL,
+                         uint32_t recordFlags = 0)
+
+ +--- + +# Pixel + +## Storage + +# Pixmap + +# Class SkPixmap + +# Rasterizer + +# Class SkRasterizer + +## Layer + +# Reference Count + +# Class sk_sp + +# Round Rect + +# Class SkRRect + + +## dump + +
+void dump() const
+
+ +--- + + +## dumpHex + +
+void dumpHex() const
+
+ +--- + +# RSXform + +# Struct SkRSXform + +# Shader + +# Class SkShader + +## Enum SkShader::TileMode + +### Constants + + + + + + +
SkShader::kClamp_TileMode 0
+ + +## MakeBitmapShader + +
+static sk_sp MakeBitmapShader(const SkBitmap& src, TileMode tmx,
+                                        TileMode tmy,
+                                        const SkMatrix* localMatrix = nullptr)
+
+ +--- + +## Gradient + +# Sprite + +# Stream + +# Class SkFlattenable + +# String + +# Class SkString + +# Surface + +# Class SkSurface + + +## MakeRasterDirect + +
+static sk_sp MakeRasterDirect(const SkImageInfo&, void* pixels,
+                                         size_t rowBytes,
+                                         const SkSurfaceProps* = nullptr)
+
+ +--- + +## Properties + +# Class SkSurfaceProps + +## Enum SkSurfaceProps::InitType + +### Constants + + + + + + +
SkSurfaceProps::kLegacyFontHost_InitType 0
+ +## GPU + +## Raster + +# SVG + +## Canvas + +## Arc + +# Text + +# Text Blob + +# Class SkTextBlob + +# Vertices + +## Colors + +## Texs + +# Read Buffer + +# Struct SkReadBuffer + +# Write Buffer + +# Struct SkWriteBuffer diff --git a/site/user/api/usingBookmaker.md b/site/user/api/usingBookmaker.md new file mode 100644 index 0000000000..d98f52bc79 --- /dev/null +++ b/site/user/api/usingBookmaker.md @@ -0,0 +1,79 @@ +using Bookmaker +=== + +# Bookmaker +How to use the Bookmaker utility. + +Get the fiddle command line interface tool. + +
+$ go get go.skia.org/infra/fiddle/go/fiddlecli
+ +Get the Bookmaker CL and build it. + +
+$ git cl patch 9919
+$ ninja -C out/dir bookmaker
+ +Generate an starter Bookmaker file from an existing include. +This writes SkXXX.bmh in the current directory, which is +out/dir/obj/ from an IDE. + +
+$ ./out/dir/bookmaker -t -i include/core/SkXXX.h
+ +Use your favorite editor to fill out SkXXX.bmh. + +Generate fiddle.json from all examples, including the ones you just wrote. +Error checking is syntatic: starting keywords are closed, keywords have the +correct parents. +If you run Bookmaker inside Visual Studio, you can click on errors and it +will take you to the source line in question. + +
+$ ./out/dir/bookmaker -e fiddle.json -b current_directory
+ +Once complete, run fiddlecli to generate the example hashes. +Errors are contained by the output but aren't reported yet. + +
+$ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json
+ +Generate bmh SkXXX.md from SkXXX.bmh and fiddleout.json. +Error checking includes: undefined references, fiddle compiler errors, +missing or mismatched printf output. +Again, you can click on any errors inside Visual Studio. + +
+$ ./out/dir/bookmaker -r site/user/api -b current_directory -f fiddleout.json
+ +The original include may have changed since you started creating the markdown. +Check to see if it is up to date. +This reports if a method no longer exists or its parameters have changed. + +
+$ ./out/dir/bookmaker -x -b current_directory/SkXXX.bmh -i include/core/SkXXX.h
+ +# Bugs + + +overaggressive reference finding in code block +missing examples +redundant examples -- got tired so used the same one more than once +some examples need vertical resizing +list doesn't work (ironic, huh)
+ +# To Do + + +check that all methods have one line descriptions in overview +see also -- anything that can be done automatically? maybe any ref shows up everywhere +index by example png +generate pdf or pdf-like out +generate b/w out instead of color -- have b/w versions of examples? +formalize voice / syntax for parts of topic and method +write bmh data back into include +have a way to write one block that covers multiple nearly indentical methods? +may want to do this for pdf view as well +write a one-method-per-page online view?
+ -- cgit v1.2.3