diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/SkBitmap_Reference.bmh | 77 | ||||
| -rw-r--r-- | docs/SkCanvas_Reference.bmh | 129 | ||||
| -rw-r--r-- | docs/SkIPoint16_Reference.bmh | 134 | ||||
| -rw-r--r-- | docs/SkIPoint_Reference.bmh | 452 | ||||
| -rw-r--r-- | docs/SkImage_Reference.bmh | 1334 | ||||
| -rw-r--r-- | docs/SkMatrix_Reference.bmh | 8 | ||||
| -rw-r--r-- | docs/SkPaint_Reference.bmh | 31 | ||||
| -rw-r--r-- | docs/SkPath_Reference.bmh | 14 | ||||
| -rw-r--r-- | docs/SkPoint_Reference.bmh | 1251 | ||||
| -rw-r--r-- | docs/SkRect_Reference.bmh | 4 | ||||
| -rw-r--r-- | docs/SkSurface_Reference.bmh | 1601 | ||||
| -rw-r--r-- | docs/undocumented.bmh | 285 |
12 files changed, 5058 insertions, 262 deletions
diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh index 7da6797dff..6f65688d2d 100644 --- a/docs/SkBitmap_Reference.bmh +++ b/docs/SkBitmap_Reference.bmh @@ -110,7 +110,7 @@ is useful to position one or more Bitmaps within a shared pixel array. # getPixels # Returns address of pixels. ## # getSubset # Returns bounds offset by origin. ## # hasHardwareMipMap # Returns Mip_Map support present; Android only. ## -# height # Returns pixel row count. ## +# height() # Returns pixel row count. ## # info() # Returns Image_Info. ## # installMaskPixels # Creates Pixel_Ref from Mask. ## # installPixels # Creates Pixel_Ref, with optional release function. ## @@ -477,7 +477,7 @@ width: 56 height: 56 color: BGRA_8888 alpha: Opaque #Method int width() const -Returns pixel count in each pixel row. Should be equal or less than: +Returns pixel count in each row. Should be equal or less than: #Formula rowBytes() / info().bytesPerPixel() @@ -1385,7 +1385,6 @@ Color_Space values, rowBytes of zero is treated as imageInfo.minRowBytes. Calls reset() and returns false if: #List # rowBytes exceeds 31 bits ## -# imageInfo.width() times imageInfo.bytesPerPixel exceeds 31 bits ## # imageInfo.width() is negative ## # imageInfo.height() is negative ## # rowBytes is positive and less than imageInfo.width() times imageInfo.bytesPerPixel ## @@ -1446,8 +1445,7 @@ Sets Image_Info to info following the rules in setInfo and allocates pixel memory. If flags is kZeroPixels_AllocFlag, memory is zeroed. Returns false and calls reset() if Image_Info could not be set, or memory could -not be allocated, or memory size exceeds 31 bits, or memory could not optionally -be zeroed. +not be allocated, or memory could not optionally be zeroed. On most platforms, allocating pixel memory may succeed even though there is not sufficient memory to hold pixels; allocation does not take place @@ -1464,25 +1462,15 @@ eraseColor(SK_ColorTRANSPARENT). #Return true if pixels allocation is successful ## #Example -#Description -For width of 100,000, height of 100,000, and 4 bytes per pixel, Pixel_Ref -requires 40,000,000,000 bytes of storage. Allocator implemented -internally by SkMallocPixelRef::MakeZeroed limits the maximum memory allowed; -the allocation must fit in 31 bits. -## SkBitmap bitmap; - int loop = 0; - while (++loop) { - SkDebugf("attempt %d\n", loop); - if (!bitmap.tryAllocPixelsFlags(SkImageInfo::MakeN32(100000, 100000, kOpaque_SkAlphaType), - SkBitmap::kZeroPixels_AllocFlag)) { - SkDebugf("failed!\n"); - break; - } + if (!bitmap.tryAllocPixelsFlags(SkImageInfo::MakeN32(10000, 10000, kOpaque_SkAlphaType), + SkBitmap::kZeroPixels_AllocFlag)) { + SkDebugf("bitmap allocation failed!\n"); + } else { + SkDebugf("bitmap allocation succeeded!\n"); } #StdOut -attempt 1 -failed! +bitmap allocation succeeded! ## ## @@ -1498,7 +1486,7 @@ Sets Image_Info to info following the rules in setInfo and allocates pixel memory. If flags is kZeroPixels_AllocFlag, memory is zeroed. Aborts execution if Image_Info could not be set, or memory could -not be allocated, or memory size exceeds 31 bits, or memory could not optionally +not be allocated, or memory could not optionally be zeroed. Abort steps may be provided by the user at compile time by defining SK_ABORT. @@ -1593,7 +1581,7 @@ memory. rowBytes must equal or exceed info.width() times info.bytesPerPixel(), or equal zero. Pass in zero for rowBytes to compute the minimum valid value. Aborts execution if Image_Info could not be set, or memory could -not be allocated, or memory size exceeds 31 bits. Abort steps may be provided by +not be allocated. Abort steps may be provided by the user at compile time by defining SK_ABORT. On most platforms, allocating pixel memory may succeed even though there is @@ -1665,7 +1653,7 @@ Sets Image_Info to info following the rules in setInfo and allocates pixel memory. Aborts execution if Image_Info could not be set, or memory could -not be allocated, or memory size exceeds 31 bits. Abort steps may be provided by +not be allocated. Abort steps may be provided by the user at compile time by defining SK_ABORT. On most platforms, allocating pixel memory may succeed even though there is @@ -1695,7 +1683,7 @@ for (int y : { 0, 64, 128, 192 } ) { #Method bool SK_WARN_UNUSED_RESULT tryAllocN32Pixels(int width, int height, bool isOpaque = false) -Sets Image_Info to width, height, and the native Color_Type; and allocates +Sets Image_Info to width, height, and Native_Color_Type; and allocates pixel memory. If isOpaque is true, sets Image_Info to kOpaque_SkAlphaType; otherwise, sets to kPremul_SkAlphaType. @@ -1704,8 +1692,8 @@ or height is negative. Returns false if allocation fails. -Use to create Bitmap that matches native pixel arrangement on the platform, -to draw without converting its pixel format. +Use to create Bitmap that matches SkPMColor, the native pixel arrangement on +the platform. Bitmap drawn to output device skips converting its pixel format. #Param width pixel column count; must be zero or greater ## #Param height pixel row count; must be zero or greater ## @@ -1736,7 +1724,7 @@ to draw without converting its pixel format. #Method void allocN32Pixels(int width, int height, bool isOpaque = false) -Sets Image_Info to width, height, and the native Color_Type; and allocates +Sets Image_Info to width, height, and the Native_Color_Type; and allocates pixel memory. If isOpaque is true, sets Image_Info to kPremul_SkAlphaType; otherwise, sets to kOpaque_SkAlphaType. @@ -1744,8 +1732,8 @@ Aborts if width exceeds 29 bits or is negative, or height is negative, or allocation fails. Abort steps may be provided by the user at compile time by defining SK_ABORT. -Use to create Bitmap that matches native pixel arrangement on the platform, -to draw without converting its pixel format. +Use to create Bitmap that matches SkPMColor, the native pixel arrangement on +the platform. Bitmap drawn to output device skips converting its pixel format. #Param width pixel column count; must be zero or greater ## #Param height pixel row count; must be zero or greater ## @@ -2004,8 +1992,7 @@ of Bitmap and Pixel_Ref. Allocates pixel memory with HeapAllocator, and replaces existing Pixel_Ref. The allocation size is determined by Image_Info width, height, and Color_Type. -Returns false if info().colorType is kUnknown_SkColorType, or allocation exceeds -31 bits, or allocation fails. +Returns false if info().colorType is kUnknown_SkColorType, or allocation fails. #Return true if the allocation succeeds ## @@ -2041,8 +2028,8 @@ Pixel_Ref with set1. Allocates pixel memory with HeapAllocator, and replaces existing Pixel_Ref. The allocation size is determined by Image_Info width, height, and Color_Type. -Aborts if info().colorType is kUnknown_SkColorType, or allocation exceeds -31 bits, or allocation fails. Abort steps may be provided by the user at compile +Aborts if info().colorType is kUnknown_SkColorType, or allocation fails. +Abort steps may be provided by the user at compile time by defining SK_ABORT. #Example @@ -3400,17 +3387,17 @@ pixmap contents become invalid on any future change to Bitmap. } } #StdOut - ------ - --xxx- - -x--x- - ----x- - ---xx- - --xx-- - --x--- - ------ - --x--- - --x--- - ------ +------
+-xxx--
+x---x-
+----x-
+---x--
+--x---
+--x---
+------
+--x---
+--x---
+------ #StdOut ## ## diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh index aec7610739..55dc86ba35 100644 --- a/docs/SkCanvas_Reference.bmh +++ b/docs/SkCanvas_Reference.bmh @@ -109,7 +109,7 @@ when no Surface is required, and some helpers implicitly create Raster_Surface. # drawLine # Draws line segment between two points.## # drawOval # Draws Oval using Clip, Matrix, and Paint. ## # drawPaint # Fills Clip with Paint. ## -# drawPatch # Draws Coons patch. ## +# drawPatch # Draws Coons_Patch. ## # drawPath # Draws Path using Clip, Matrix, and Paint. ## # drawPicture # Draws Picture using Clip and Matrix. ## # drawPoint # Draws point at (x, y) position. ## @@ -168,11 +168,11 @@ when no Surface is required, and some helpers implicitly create Raster_Surface. # ------------------------------------------------------------------------------ -#Method static std::unique_ptr<SkCanvas> MakeRasterDirect(const SkImageInfo& info, - void* pixels, size_t rowBytes) +#Method static std::unique_ptr<SkCanvas> MakeRasterDirect(const SkImageInfo& info, void* pixels, + size_t rowBytes, + const SkSurfaceProps* props = nullptr) Allocates raster Canvas that will draw directly into pixels. -To access pixels after drawing, call flush() or peekPixels. Canvas is returned if all parameters are valid. Valid parameters include: @@ -186,6 +186,8 @@ If rowBytes is greater than zero, it must be equal to or greater than info width times bytes required for Image_Color_Type. Pixel buffer size should be info height times computed rowBytes. +Pixels are not initialized. +To access pixels after drawing, call flush() or peekPixels. #Param info width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, of Raster_Surface; width, or height, or both, may be zero @@ -194,6 +196,9 @@ Pixel buffer size should be info height times computed rowBytes. ## #Param rowBytes interval from one Surface row to the next, or zero ## +#Param props LCD striping orientation and setting for device independent fonts; + may be nullptr +## #Return Canvas if all parameters are valid; otherwise, nullptr ## @@ -205,7 +210,7 @@ Pixel buffer size should be info height times computed rowBytes. void draw(SkCanvas* ) { SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3); // device aligned, 32 bpp, Premultiplied const size_t minRowBytes = info.minRowBytes(); // bytes used by one bitmap row - const size_t size = info.getSafeSize(minRowBytes); // bytes used by all rows + const size_t size = info.computeMinByteSize(); // bytes used by all rows SkAutoTMalloc<SkPMColor> storage(size); // allocate storage for pixels SkPMColor* pixels = storage.get(); // get pointer to allocated storage // create a SkCanvas backed by a raster device, and delete it when the @@ -1003,10 +1008,10 @@ Canvas or Surface call may invalidate the pixmap values. int srcX, int srcY) Copies Rect of pixels from Canvas into dstPixels. Matrix and Clip are -ignored. Source Rect corners are (srcX, srcY) and -(imageInfo().width(), imageInfo().height()). +ignored. -Destination Rect corners are (0, 0) and (bitmap.width(), bitmap.height()). +Source Rect corners are (srcX, srcY) and (imageInfo().width(), imageInfo().height()). +Destination Rect corners are (0, 0) and (dstInfo.width(), dstInfo.height()). Copies each readable pixel intersecting both rectangles, without scaling, converting to dstInfo.colorType() and dstInfo.alphaType() if required. @@ -1046,7 +1051,7 @@ Does not copy, and returns false if: #Description A black circle drawn on a blue background provides an image to copy. readPixels copies one quarter of the canvas into each of the four corners. - The Layer draws over the image. + The copied quarter circles overdraw the original circle. ## canvas->clear(SK_ColorBLUE); SkPaint paint; @@ -1095,10 +1100,10 @@ Does not copy, and returns false if: #Method bool readPixels(const SkPixmap& pixmap, int srcX, int srcY) Copies Rect of pixels from Canvas into pixmap. Matrix and Clip are -ignored. Source Rect corners are (srcX, srcY) and -(imageInfo().width(), imageInfo().height()). +ignored. -Destination Rect corners are (0, 0) and (bitmap.width(), bitmap.height()). +Source Rect corners are (srcX, srcY) and (imageInfo().width(), imageInfo().height()). +Destination Rect corners are (0, 0) and (pixmap.width(), pixmap.height()). Copies each readable pixel intersecting both rectangles, without scaling, converting to pixmap.colorType() and pixmap.alphaType() if required. @@ -1158,9 +1163,9 @@ Does not copy, and returns false if: #Method bool readPixels(const SkBitmap& bitmap, int srcX, int srcY) Copies Rect of pixels from Canvas into bitmap. Matrix and Clip are -ignored. Source Rect corners are (srcX, srcY) and -(imageInfo().width(), imageInfo().height()). +ignored. +Source Rect corners are (srcX, srcY) and (imageInfo().width(), imageInfo().height()). Destination Rect corners are (0, 0) and (bitmap.width(), bitmap.height()). Copies each readable pixel intersecting both rectangles, without scaling, converting to bitmap.colorType() and bitmap.alphaType() if required. @@ -1583,7 +1588,7 @@ Canvas. #Height 128 void draw(SkCanvas* canvas) { SkPaint paint, blur; - blur.setImageFilter(SkImageFilter::MakeBlur(3, 3, nullptr)); + blur.setImageFilter(SkBlurImageFilter::Make(3, 3, nullptr)); canvas->saveLayer(nullptr, &blur); SkRect rect = { 25, 25, 50, 50}; canvas->drawRect(rect, paint); @@ -1631,7 +1636,7 @@ Image_Filter blurs past edge of Layer so red rectangle is blurred on all sides. #Height 128 void draw(SkCanvas* canvas) { SkPaint paint, blur; - blur.setImageFilter(SkImageFilter::MakeBlur(3, 3, nullptr)); + blur.setImageFilter(SkBlurImageFilter::Make(3, 3, nullptr)); canvas->saveLayer(SkRect::MakeWH(90, 90), &blur); SkRect rect = { 25, 25, 50, 50}; canvas->drawRect(rect, paint); @@ -1753,8 +1758,6 @@ Call restoreToCount with returned value to restore this and subsequent saves. kInitWithPrevious_SaveLayerFlag = 1 << 2, kDontClipToLayer_Legacy_SaveLayerFlag = kDontClipToLayer_PrivateSaveLayerFlag, }; - - typedef uint32_t SaveLayerFlags; ## SaveLayerFlags provides options that may be used in any combination in SaveLayerRec, @@ -1810,6 +1813,10 @@ void draw(SkCanvas* canvas) { #Enum ## +#Typedef uint32_t SaveLayerFlags + +## + #Struct SaveLayerRec #Code @@ -4421,7 +4428,7 @@ void draw(SkCanvas* canvas) { Draw Bitmap bitmap, 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, +If Paint paint is not nullptr, 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. @@ -5608,12 +5615,12 @@ void draw(SkCanvas* canvas) { #Method void drawPatch(const SkPoint cubics[12], const SkColor colors[4], const SkPoint texCoords[4], SkBlendMode mode, const SkPaint& paint) -Draws a Coons patch: the interpolation of four cubics with shared corners, +Draws a 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 Shader, Color_Filter, +Coons_Patch uses Clip and Matrix, paint 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 +as Coons_Patch texture; Blend_Mode mode combines Color colors and Shader if both are provided. Point array cubics specifies four Cubics starting at the top-left corner, @@ -5667,12 +5674,12 @@ void draw(SkCanvas* canvas) { #Method void drawPatch(const SkPoint cubics[12], const SkColor colors[4], const SkPoint texCoords[4], const SkPaint& paint) -Draws Cubic Coons patch: the interpolation of four cubics with shared corners, +Draws 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 Shader, Color_Filter, +Coons_Patch uses Clip and Matrix, paint 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 +as Coons_Patch texture; Blend_Mode mode combines Color colors and Shader if both are provided. Point array cubics specifies four Cubics starting at the top-left corner, @@ -6141,17 +6148,17 @@ Preserves Canvas save count. Optionally saves Canvas Clip and Matrix. #Example #Height 128 - SkPaint p;
- p.setAntiAlias(true);
- p.setTextSize(64);
- for (SkScalar sx : { -1, 1 } ) {
- for (SkScalar sy : { -1, 1 } ) {
- SkAutoCanvasRestore autoRestore(canvas, true);
- SkMatrix m = SkMatrix::MakeAll(sx, 1, 96, 0, sy, 64, 0, 0, 1);
- canvas->concat(m);
- canvas->drawString("R", 0, 0, p);
- }
- }
+ SkPaint p; + p.setAntiAlias(true); + p.setTextSize(64); + for (SkScalar sx : { -1, 1 } ) { + for (SkScalar sy : { -1, 1 } ) { + SkAutoCanvasRestore autoRestore(canvas, true); + SkMatrix m = SkMatrix::MakeAll(sx, 1, 96, 0, sy, 64, 0, 0, 1); + canvas->concat(m); + canvas->drawString("R", 0, 0, p); + } + } ## #SeeAlso SkCanvas::save SkCanvas::restore @@ -6176,31 +6183,31 @@ Restores Canvas to saved state immediately. Subsequent calls and ~SkAutoCanvasRestore have no effect. #Example -for (bool callRestore : { false, true } ) {
- for (bool saveCanvas : {false, true} ) {
- SkAutoCanvasRestore autoRestore(canvas, saveCanvas);
- if (!saveCanvas) {
- canvas->save();
- }
- SkDebugf("saveCanvas: %s before restore: %d\n",
- saveCanvas ? "true" : "false", canvas->getSaveCount());
- if (callRestore) autoRestore.restore();
- SkDebugf("saveCanvas: %s after restore: %d\n",
- saveCanvas ? "true" : "false", canvas->getSaveCount());
- }
-}
-SkDebugf("final count: %d\n", canvas->getSaveCount());
-#StdOut
-saveCanvas: false before restore: 2
-saveCanvas: false after restore: 2
-saveCanvas: true before restore: 2
-saveCanvas: true after restore: 2
-saveCanvas: false before restore: 2
-saveCanvas: false after restore: 1
-saveCanvas: true before restore: 2
-saveCanvas: true after restore: 1
-final count: 1
-##
+for (bool callRestore : { false, true } ) { + for (bool saveCanvas : {false, true} ) { + SkAutoCanvasRestore autoRestore(canvas, saveCanvas); + if (!saveCanvas) { + canvas->save(); + } + SkDebugf("saveCanvas: %s before restore: %d\n", + saveCanvas ? "true" : "false", canvas->getSaveCount()); + if (callRestore) autoRestore.restore(); + SkDebugf("saveCanvas: %s after restore: %d\n", + saveCanvas ? "true" : "false", canvas->getSaveCount()); + } +} +SkDebugf("final count: %d\n", canvas->getSaveCount()); +#StdOut +saveCanvas: false before restore: 2 +saveCanvas: false after restore: 2 +saveCanvas: true before restore: 2 +saveCanvas: true after restore: 2 +saveCanvas: false before restore: 2 +saveCanvas: false after restore: 1 +saveCanvas: true before restore: 2 +saveCanvas: true after restore: 1 +final count: 1 +## ## #SeeAlso SkCanvas::save SkCanvas::restore diff --git a/docs/SkIPoint16_Reference.bmh b/docs/SkIPoint16_Reference.bmh new file mode 100644 index 0000000000..b5c3cfee99 --- /dev/null +++ b/docs/SkIPoint16_Reference.bmh @@ -0,0 +1,134 @@ +#Topic IPoint16 +#Alias IPoint16_Reference + +#Struct SkIPoint16 + +SkIPoint holds two 16 bit integer coordinates + +#Topic Overview + +#Subtopic Subtopics +#ToDo manually add subtopics ## +#Table +#Legend +# topics # description ## +#Legend ## +#Table ## +## + +#Subtopic Member_Functions +#Table +#Legend +# description # function ## +#Legend ## +# Make # Constructs from integer inputs. ## +# set() # Sets to integer input. ## +# x() # Returns fX. ## +# y() # Returns fY. ## +#Table ## +#Subtopic ## + +#Topic ## + +#Member int16_t fX +x-axis value used by IPoint16. +## + +#Member int16_t fY +y-axis value used by IPoint16. +## + +# ------------------------------------------------------------------------------ + +#Method static constexpr SkIPoint16 Make(int x, int y) + +Sets fX to x, fY to y. If SK_DEBUG is defined, asserts +if x or y does not fit in 16 bits. + +#Param x integer x-axis value of constructed IPoint ## +#Param y integer y-axis value of constructed IPoint ## + +#Return IPoint16 (x, y) ## + +#Example +SkIPoint16 pt1 = {45, 66}; +SkIPoint16 pt2 = SkIPoint16::Make(45, 66); +SkDebugf("pt1.fX %c= pt2.fX\n", pt1.fX == pt2.fX ? '=' : '!'); +SkDebugf("pt1.fY %c= pt2.fY\n", pt1.fY == pt2.fY ? '=' : '!'); +#StdOut +pt1.fX == pt2.fX +pt1.fY == pt2.fY +## +## + +#SeeAlso set() SkPoint::iset() SkIPoint::Make + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int16_t x() const + +Returns x-axis value of IPoint16. + +#Return fX ## + +#Example +SkIPoint16 pt1 = {45, 66}; +SkDebugf("pt1.fX %c= pt1.x()\n", pt1.fX == pt1.x() ? '=' : '!'); +#StdOut +pt1.fX == pt1.x() +## +## + +#SeeAlso y() SkIPoint::x() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int16_t y() const + +Returns y-axis value of IPoint. + +#Return fY ## + +#Example +SkIPoint16 pt1 = {45, 66}; +SkDebugf("pt1.fY %c= pt1.y()\n", pt1.fY == pt1.y() ? '=' : '!'); +#StdOut +pt1.fY == pt1.y() +## +## + +#SeeAlso x() SkPoint::y() SkIPoint::y() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void set(int x, int y) + +Sets fX to x and fY to y. + +#Param x new value for fX ## +#Param y new value for fY ## + +#Example +SkIPoint16 pt1, pt2 = { SK_MinS16, SK_MaxS16 }; +pt1.set(SK_MinS16, SK_MaxS16); +SkDebugf("pt1.fX %c= pt2.fX\n", pt1.fX == pt2.fX ? '=' : '!'); +SkDebugf("pt1.fY %c= pt2.fY\n", pt1.fY == pt2.fY ? '=' : '!'); +#StdOut +pt1.fX == pt2.fX +pt1.fY == pt2.fY +## +## + +#SeeAlso Make SkPoint::set + +#Method ## + +#Struct SkIPoint16 ## + +#Topic IPoint16 ## diff --git a/docs/SkIPoint_Reference.bmh b/docs/SkIPoint_Reference.bmh new file mode 100644 index 0000000000..178a14f2c3 --- /dev/null +++ b/docs/SkIPoint_Reference.bmh @@ -0,0 +1,452 @@ +#Topic IPoint +#Alias IPoints +#Alias IPoint_Reference + +#Struct SkIPoint + +SkIPoint holds two 32 bit integer coordinates + +#Topic Overview + +#Subtopic Subtopics +#ToDo manually add subtopics ## +#Table +#Legend +# topics # description ## +#Legend ## +#Table ## +## + +#Subtopic Operators +#Table +#Legend +# description # function ## +#Legend ## +# SkIPoint operator-()_const # Reverses sign of IPoint. ## +# SkIPoint operator+(const SkIPoint& a, const SkIVector& b) # Returns IPoint offset by IVector. ## +# SkIVector operator-(const SkIPoint& a, const SkIPoint& b) # Returns IVector between IPoints. ## +# bool operator!=(const SkIPoint& a, const SkIPoint& b) # Returns true if IPoints are unequal. ## +# bool operator==(const SkIPoint& a, const SkIPoint& b) # Returns true if IPoints are equal. ## +# void operator+=(const SkIVector& v) # Adds IVector to IPoint. ## +# void operator-=(const SkIVector& v) # Subtracts IVector from IPoint. ## +#Table ## +#Subtopic ## + +#Subtopic Member_Functions +#Table +#Legend +# description # function ## +#Legend ## +# Make # Constructs from integer inputs. ## +# equals() # Returns true if members are equal. ## +# isZero # Returns true if both members equal zero. ## +# set() # Sets to integer input. ## +# x() # Returns fX. ## +# y() # Returns fY. ## +#Table ## +#Subtopic ## + +#Topic ## + +#Member int32_t fX +x-axis value used by IPoint. +## + +#Member int32_t fY +y-axis value used by IPoint. +## + +# ------------------------------------------------------------------------------ + +#Method static constexpr SkIPoint Make(int32_t x, int32_t y) + +Sets fX to x, fY to y. + +#Param x integer x-axis value of constructed IPoint ## +#Param y integer y-axis value of constructed IPoint ## + +#Return IPoint (x, y) ## + +#Example +SkIPoint pt1 = {45, 66}; +SkIPoint pt2 = SkIPoint::Make(45, 66); +SkDebugf("pt1 %c= pt2\n", pt1 == pt2 ? '=' : '!'); +#StdOut +pt1 == pt2 +## +## + +#SeeAlso set() SkPoint::iset() SkPoint::Make SkIPoint16::Make + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int32_t x() const + +Returns x-axis value of IPoint. + +#Return fX ## + +#Example +SkIPoint pt1 = {45, 66}; +SkDebugf("pt1.fX %c= pt1.x()\n", pt1.fX == pt1.x() ? '=' : '!'); +#StdOut +pt1.fX == pt1.x() +## +## + +#SeeAlso y() SkPoint::x() SkIPoint16::x() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int32_t y() const + +Returns y-axis value of IPoint. + +#Return fY ## + +#Example +SkIPoint pt1 = {45, 66}; +SkDebugf("pt1.fY %c= pt1.y()\n", pt1.fY == pt1.y() ? '=' : '!'); +#StdOut +pt1.fY == pt1.y() +## +## + +#SeeAlso x() SkPoint::y() SkIPoint16::y() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isZero() const + +Returns true if fX and fY are both zero. + +#Return true if fX is zero and fY is zero ## + +#Example +SkIPoint pt = { 0, -0};
+SkDebugf("pt.isZero() == %s\n", pt.isZero() ? "true" : "false"); +#StdOut +pt.isZero() == true
+## +## + +#SeeAlso SkPoint::isZero + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void set(int32_t x, int32_t y) + +Sets fX to x and fY to y. + +#Param x new value for fX ## +#Param y new value for fY ## + +#Example +SkIPoint pt1, pt2 = { SK_MinS32, SK_MaxS32 }; +pt1.set(SK_MinS32, SK_MaxS32); +SkDebugf("pt1 %c= pt2\n", pt1 == pt2 ? '=' : '!'); +#StdOut +pt1 == pt2 +## +## + +#SeeAlso Make SkIPoint16::set + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkIPoint operator-()_const + +Returns IPoint changing the signs of fX and fY. + +#Return IPoint as (-fX, -fY) ## + +#Example +SkIPoint test[] = { {0, -0}, {-1, -2},
+ { SK_MaxS32, SK_MinS32 },
+ { SK_NaN32, -SK_NaN32 } };
+for (const SkIPoint& pt : test) {
+ SkIPoint negPt = -pt;
+ SkDebugf("pt: %d, %d negate: %d, %d\n", pt.fX, pt.fY, negPt.fX, negPt.fY);
+} +#StdOut +pt: 0, 0 negate: 0, 0
+pt: -1, -2 negate: 1, 2
+pt: 2147483647, -2147483647 negate: -2147483647, 2147483647
+pt: -2147483648, -2147483648 negate: -2147483648, -2147483648 +## +## + +#SeeAlso operator-(const SkIPoint& a, const SkIPoint& b) operator-=(const SkIVector& v) SkPoint::operator-()_const + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void operator+=(const SkIVector& v) + +Offsets IPoint by IVector v. Sets IPoint to +#Formula +(fX + v.fX, fY + v.fY) +## +. + +#Param v IVector to add ## + +#Example +#Height 64 + auto draw_lines = [=](const SkIPoint pts[], size_t count, SkPaint& paint) -> void {
+ for (size_t i = 0; i < count - 1; ++i) {
+ SkPoint p0, p1;
+ p0.iset(pts[i]);
+ p1.iset(pts[i + 1]);
+ canvas->drawLine(p0, p1, paint);
+ }
+ };
+ SkIPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 } };
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->scale(30, 15);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+ points[1] += {1, 1};
+ points[2] += {-1, -1};
+ paint.setColor(SK_ColorRED);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+## + +#SeeAlso operator+(const SkIPoint& a, const SkIVector& b) SkPoint::operator+=(const SkVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void operator-=(const SkIVector& v) + +Subtracts IVector v from IPoint. Sets IPoint to: +#Formula +(fX - v.fX, fY - v.fY) +## +. + +#Param v IVector to subtract ## + +#Example +#Height 64 + auto draw_lines = [=](const SkIPoint pts[], size_t count, SkPaint& paint) -> void {
+ for (size_t i = 0; i < count - 1; ++i) {
+ SkPoint p0, p1;
+ p0.iset(pts[i]);
+ p1.iset(pts[i + 1]);
+ canvas->drawLine(p0, p1, paint);
+ }
+ };
+ SkIPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 } };
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->scale(30, 15);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+ points[1] -= {1, 1};
+ points[2] -= {-1, -1};
+ paint.setColor(SK_ColorRED);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+## + +#SeeAlso operator-(const SkIPoint& a, const SkIPoint& b) SkPoint::operator-=(const SkVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool equals(int32_t x, int32_t y) const + +Returns true if IPoint is equivalent to IPoint constructed from (x, y). + +#Param x value compared with fX ## +#Param y value compared with fY ## + +#Return true if IPoint equals (x, y) ## + +#Example +SkIPoint test[] = { {0, -0}, {-1, -2}, {SK_MaxS32, -1}, {SK_NaN32, -1} };
+for (const SkIPoint& pt : test) {
+ SkDebugf("pt: %d, %d %c= pt\n", pt.fX, pt.fY, pt.equals(pt.fX, pt.fY) ? '=' : '!');
+} +#StdOut +pt: 0, 0 == pt
+pt: -1, -2 == pt
+pt: 2147483647, -1 == pt
+pt: -2147483648, -1 == pt +## +## + +#SeeAlso operator==(const SkIPoint& a, const SkIPoint& b) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool operator==(const SkIPoint& a, const SkIPoint& b) + +Returns true if a is equivalent to b. + +#Param a IPoint to compare ## +#Param b IPoint to compare ## + +#Return true if a.fX == b.fX and a.fY == b.fY ## + +#Example +SkIPoint test[] = { {0, -0}, {-1, -2}, {SK_MaxS32, -1}, {SK_NaN32, -1} };
+for (const SkIPoint& pt : test) {
+ SkDebugf("pt: %d, %d %c= pt\n", pt.fX, pt.fY, pt == pt ? '=' : '!');
+} +#StdOut +pt: 0, 0 == pt
+pt: -1, -2 == pt
+pt: 2147483647, -1 == pt
+pt: -2147483648, -1 == pt +## +## + +#SeeAlso equals() operator!=(const SkIPoint& a, const SkIPoint& b) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool operator!=(const SkIPoint& a, const SkIPoint& b) + +Returns true if a is not equivalent to b. + +#Param a IPoint to compare ## +#Param b IPoint to compare ## + +#Return true if a.fX != b.fX or a.fY != b.fY ## + +#Example +SkIPoint test[] = { {0, -0}, {-1, -2}, {SK_MaxS32, -1}, {SK_NaN32, -1} };
+for (const SkIPoint& pt : test) {
+ SkDebugf("pt: %d, %d %c= pt\n", pt.fX, pt.fY, pt != pt ? '!' : '=');
+} +#StdOut +pt: 0, 0 == pt
+pt: -1, -2 == pt
+pt: 2147483647, -1 == pt
+pt: -2147483648, -1 == pt +## +## + +#SeeAlso operator==(const SkIPoint& a, const SkIPoint& b) equals() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkIVector operator-(const SkIPoint& a, const SkIPoint& b) + +Returns IVector from b to a; computed as +#Formula +(a.fX - b.fX, a.fY - b.fY) +## +. + +Can also be used to subtract IVector from IVector, returning IVector. + +#Param a IPoint or IVector to subtract from ## +#Param b IVector to subtract ## + +#Return IVector from b to a ## + +#Example +#Height 64 + auto draw_lines = [=](const SkIPoint pts[], size_t count, SkPaint& paint) -> void {
+ for (size_t i = 0; i < count - 1; ++i) {
+ SkPoint p0, p1;
+ p0.iset(pts[i]);
+ p1.iset(pts[i + 1]);
+ canvas->drawLine(p0, p1, paint);
+ }
+ };
+ SkIPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 } };
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->scale(30, 15);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+ points[1] += points[0] - points[3];
+ points[2] -= points[1] - points[0];
+ paint.setColor(SK_ColorRED);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+## + +#SeeAlso operator-=(const SkIVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkIPoint operator+(const SkIPoint& a, const SkIVector& b) + +Returns IPoint resulting from IPoint a offset by IVector b, computed as: +#Formula +(a.fX + b.fX, a.fY + b.fY) +## +. + +Can also be used to offset IPoint b by IVector a, returning IPoint. +Can also be used to add IVector to IVector, returning IVector. + +#Param a IPoint or IVector to add to ## +#Param b IPoint or IVector to add ## + +#Return IPoint equal to a offset by b ## + +#Example +#Height 128 + auto draw_lines = [=](const SkIPoint pts[], size_t count, SkPaint& paint) -> void {
+ for (size_t i = 0; i < count - 1; ++i) {
+ SkPoint p0, p1;
+ p0.iset(pts[i]);
+ p1.iset(pts[i + 1]);
+ canvas->drawLine(p0, p1, paint);
+ }
+ };
+ SkIPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 } };
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->scale(30, 15);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+ SkIPoint mod = {4, 1};
+ for (auto& point : points) {
+ point = point + mod;
+ mod.fX -= 1;
+ mod.fY += 1;
+ }
+ paint.setColor(SK_ColorRED);
+ draw_lines(points, SK_ARRAY_COUNT(points), paint);
+## + +#SeeAlso operator+=(const SkIVector& v) + +#Method ## + +#Struct SkIPoint ## + +#Topic IPoint ## + +#Topic IVector + #Alias IVectors + #Typedef SkIPoint SkIVector + #Typedef ## +## diff --git a/docs/SkImage_Reference.bmh b/docs/SkImage_Reference.bmh new file mode 100644 index 0000000000..05d38ff522 --- /dev/null +++ b/docs/SkImage_Reference.bmh @@ -0,0 +1,1334 @@ +#Topic Image +#Alias Image_Reference + +#Class SkImage + +SkImage is an abstraction for drawing a rectangle of pixels, though the +particular type of image could be actually storing its data on the GPU, or +as drawing commands (picture or PDF or otherwise), ready to be played back +into another canvas. +The content of SkImage is always immutable, though the actual storage may +change, if for example that image can be re-created via encoded data or +other means. +SkImage always has a non-zero dimensions. If there is a request to create a new +image, either directly or via SkSurface, and either of the requested dimensions +are zero, then nullptr will be returned. + +#Topic Overview + +#Subtopic Subtopics +#ToDo manually add subtopics ## +#Table +#Legend +# topics # description ## +#Legend ## +#Table ## +## + +#Subtopic Structs +#Table +#Legend +# description # struct ## +#Legend ## +# DeferredTextureImageUsageParams # ## +#Table ## +#Subtopic ## + +#Subtopic Member_Functions +#Table +#Legend +# description # function ## +#Legend ## +# MakeFromAHardwareBuffer # ## +# MakeBackendTextureFromSkImage # ## +# MakeCrossContextFromEncoded # ## +# MakeFromAHardwareBuffer # ## +# MakeFromAdoptedTexture # ## +# MakeFromBitmap # ## +# MakeFromDeferredTextureImageData # ## +# MakeFromEncoded # ## +# MakeFromGenerator # ## +# MakeFromNV12TexturesCopy # ## +# MakeFromPicture # ## +# MakeFromRaster # ## +# MakeFromTexture # ## +# MakeFromYUVTexturesCopy # ## +# MakeRasterCopy # ## +# MakeRasterData # ## +# alphaType # ## +# asLegacyBitmap # ## +# bounds # ## +# colorSpace # ## +# dimensions # ## +# encodeToData # ## +# getDeferredTextureImageData # ## +# getTexture # ## +# getTextureHandle # ## +# height # ## +# isAlphaOnly # ## +# isLazyGenerated # ## +# isOpaque # ## +# isTextureBacked # ## +# isValid # ## +# makeColorSpace # ## +# makeNonTextureImage # ## +# makeShader # ## +# makeSubset # ## +# makeTextureImage # ## +# makeWithFilter # ## +# peekPixels # ## +# readPixels # ## +# refColorSpace # ## +# refEncodedData # ## +# scalePixels # ## +# toString # ## +# uniqueID # ## +# width # ## +#Table ## +#Subtopic ## + +#Topic ## + +# ------------------------------------------------------------------------------ + +#Struct DeferredTextureImageUsageParams + +#Code +#ToDo fill this in manually ## +## + +Drawing parameters for which a deferred texture image data should be optimized. */ + +# ------------------------------------------------------------------------------ + +#Method DeferredTextureImageUsageParams(const SkMatrix matrix, const SkFilterQuality quality, + int preScaleMipLevel) + +#Param matrix incomplete ## +#Param quality incomplete ## +#Param preScaleMipLevel incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +#Member SkMatrix fMatrix +## + +#Member SkFilterQuality fQuality +## + +#Member int fPreScaleMipLevel +## + +#Struct DeferredTextureImageUsageParams ## + +#Typedef SkImageInfo Info + +## + +#Typedef void* ReleaseContext + +## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap) + +#Param pixmap incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes) + +#Param info incomplete ## +#Param pixels incomplete ## +#Param rowBytes incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext) + +## + +#Method static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap, + RasterReleaseProc rasterReleaseProc, + ReleaseContext releaseContext) + +Return a new Image referencing the specified pixels. These must remain valid and unchanged +until the specified release-proc is called, indicating that Skia no longer has a reference +to the pixels. +Returns nullptr if the requested pixmap info is unsupported. + +#Param pixmap incomplete ## +#Param rasterReleaseProc incomplete ## +#Param releaseContext incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap) + +Construct a new image from the specified bitmap. If the bitmap is marked immutable, and +its pixel memory is shareable, it may be shared instead of copied. + +#Param bitmap incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator, + const SkIRect* subset = nullptr) + +Construct a new SkImage based on the given ImageGenerator. Returns nullptr on error. +This function will always take ownership of the passed generator. +If a subset is specified, it must be contained within the generator's bounds. + +#Param imageGenerator incomplete ## +#Param subset incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr) + +Construct a new SkImage based on the specified encoded data. Returns nullptr on failure, +which can mean that the format of the encoded data was not recognized/supported. +If a subset is specified, it must be contained within the encoded data's bounds. + +#Param encoded incomplete ## +#Param subset incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Typedef void (*TextureReleaseProc)(ReleaseContext releaseContext) + +## + +#Method static sk_sp<SkImage> MakeFromTexture(GrContext* context, + const GrBackendTexture& backendTexture, + GrSurfaceOrigin origin, + SkAlphaType alphaType, + sk_sp<SkColorSpace> colorSpace) + +Create a new image from the specified descriptor. Note - the caller is responsible for +managing the lifetime of the underlying platform texture. +Will return nullptr if the specified back-end texture is unsupported. + +#Param context incomplete ## +#Param backendTexture incomplete ## +#Param origin incomplete ## +#Param alphaType incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromTexture(GrContext* context, + const GrBackendTexture& backendTexture, + GrSurfaceOrigin origin, + SkAlphaType alphaType, + sk_sp<SkColorSpace> colorSpace, + TextureReleaseProc textureReleaseProc, + ReleaseContext releaseContext) + +Create a new image from the GrBackendTexture. The underlying platform texture must stay +valid and unaltered until the specified release-proc is invoked, indicating that Skia +no longer is holding a reference to it. +Will return nullptr if the specified back-end texture is unsupported. + +#Param context incomplete ## +#Param backendTexture incomplete ## +#Param origin incomplete ## +#Param alphaType incomplete ## +#Param colorSpace incomplete ## +#Param textureReleaseProc incomplete ## +#Param releaseContext incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data, + bool buildMips, + SkColorSpace* dstColorSpace) + +Decodes and uploads the encoded data to a GPU backed image using the supplied GrContext. +That image can be safely used by other GrContexts, across thread boundaries. The GrContext +used here, and the ones used to draw this image later must be in the same OpenGL share group, +or otherwise be able to share resources. +When the image's ref count reaches zero, the original GrContext will destroy the texture, +asynchronously. +The texture will be decoded and uploaded to be suitable for use with surfaces that have the +supplied destination color space. The color space of the image itself will be determined +from the encoded data. + +#Param context incomplete ## +#Param data incomplete ## +#Param buildMips incomplete ## +#Param dstColorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context, + const GrBackendTexture& backendTexture, + GrSurfaceOrigin surfaceOrigin, + SkAlphaType alphaType = kPremul_SkAlphaType, + sk_sp<SkColorSpace> colorSpace = nullptr) + +Create a new image from the specified descriptor. Note - Skia will delete or recycle the +texture when the image is released. +Will return nullptr if the specified back-end texture is unsupported. + +#Param context incomplete ## +#Param backendTexture incomplete ## +#Param surfaceOrigin incomplete ## +#Param alphaType incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, + const GrBackendObject yuvTextureHandles[3], + const SkISize yuvSizes[3], + GrSurfaceOrigin surfaceOrigin, + sk_sp<SkColorSpace> colorSpace = nullptr) + +Create a new image by copying the pixels from the specified y, u, v textures. The data +from the textures is immediately ingested into the image and the textures can be modified or +deleted after the function returns. The image will have the dimensions of the y texture. + +#Param context incomplete ## +#Param yuvColorSpace incomplete ## +#Param yuvTextureHandles incomplete ## +#Param yuvSizes incomplete ## +#Param surfaceOrigin incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, + SkYUVColorSpace yuvColorSpace, + const GrBackendObject nv12TextureHandles[2], + const SkISize nv12Sizes[2], + GrSurfaceOrigin surfaceOrigin, + sk_sp<SkColorSpace> colorSpace = nullptr) + +Create a new image by copying the pixels from the specified y and UV_Mapping. The data +from the textures is immediately ingested into the image and the textures can be modified or +deleted after the function returns. The image will have the dimensions of the y texture. + +#Param context incomplete ## +#Param yuvColorSpace incomplete ## +#Param nv12TextureHandles incomplete ## +#Param nv12Sizes incomplete ## +#Param surfaceOrigin incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Enum BitDepth + +#Code + enum BitDepth { + kU8, + kF16, + }; +## + +#Const kU8 0 +## +#Const kF16 1 +## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Enum ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions, + const SkMatrix* matrix, const SkPaint* paint, + BitDepth bitDepth, + sk_sp<SkColorSpace> colorSpace) + +Create a new image from the specified picture. +On creation of the SkImage, snap the SkPicture to a particular BitDepth and SkColorSpace. + +#Param picture incomplete ## +#Param dimensions incomplete ## +#Param matrix incomplete ## +#Param paint incomplete ## +#Param bitDepth incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer, + SkAlphaType alphaType = kPremul_SkAlphaType, + sk_sp<SkColorSpace> colorSpace = nullptr) + + Create a new image from the an Android hardware buffer. + The new image takes a reference on the buffer. + + Only available on Android, when __ANDROID_API__ is defined to be 26 or greater. + +#Param hardwareBuffer incomplete ## +#Param alphaType incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer, + SkAlphaType alphaType = kPremul_SkAlphaType, + sk_sp<SkColorSpace> colorSpace = nullptr) + +Create a new image from the an Android hardware buffer. +The new image takes a reference on the buffer. + +#Param hardwareBuffer incomplete ## +#Param alphaType incomplete ## +#Param colorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int width() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int height() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkISize dimensions() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkIRect bounds() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method uint32_t uniqueID() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkAlphaType alphaType() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkColorSpace* colorSpace() const + +Returns Color_Space of Image. Color_Space may have been a parameter when +Image was created, or may have been parsed from encoded data. Skia may not be +able to draw image respecting returned Color_Space or draw into Surface with +returned Color_Space. + +#Return Color_Space Image was created with, or nullptr ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkColorSpace> refColorSpace() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isAlphaOnly() const + +Returns true fi the image will be drawn as a mask, with no intrinsic color of its own. + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isOpaque() const + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2, + const SkMatrix* localMatrix = nullptr) const + +#Param tileMode1 incomplete ## +#Param tileMode2 incomplete ## +#Param localMatrix incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const + +Helper version of makeShader() that specifies SkShader::kClamp_TileMode. + +#Param localMatrix incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool peekPixels(SkPixmap* pixmap) const + +If the image has direct access to its pixels (i.e. they are in local RAM) +return true, and if not null, return in the pixmap parameter the info about the +images pixels. +On failure, return false and ignore the pixmap parameter. + +#Param pixmap incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method GrTexture* getTexture() const + +DEPRECATED - +#Private +currently used by Canvas2DLayerBridge in Chromium. +## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isTextureBacked() const + +Returns true if the image is texture backed. + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isValid(GrContext* context) const + +Returns true if Image can be drawn. If context +is nullptr, tests if Image draws on Raster_Surface; Otherwise, tests if Image +draws on GPU_Surface associated with context. + +Texture-backed images may become invalid if their underlying GrContext is abandoned. Some +generator-backed images may be invalid for CPU and/or GPU. + +#Param context incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method GrBackendObject getTextureHandle(bool flushPendingGrContextIO, + GrSurfaceOrigin* origin = nullptr) const + +Retrieves the back-end API handle of the texture. If flushPendingGrContextIO then the +GrContext will issue to the back-end API any deferred I/O operations on the texture before +returning. +If 'origin' is supplied it will be filled in with the origin of the content drawn +into the image. + +#Param flushPendingGrContextIO incomplete ## +#Param origin incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Enum CachingHint + +#Code + enum CachingHint { + kAllow_CachingHint, + kDisallow_CachingHint, + }; +## + +Hints to image calls where the system might cache computed intermediates (e.g. the results +of decoding or a read-back from the GPU. Passing kAllow_CachingHint signals that the system's default +behavior is fine. Passing kDisallow_CachingHint signals that caching should be avoided. + +#Const kAllow_CachingHint 0 +## +#Const kDisallow_CachingHint 1 +## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Enum ## + +# ------------------------------------------------------------------------------ + +#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, + int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const + +Copy the pixels from the image into the specified buffer (dstPixels + dstRowBytes), +converting them into the requested format (dstInfo). The image pixels are read +starting at the specified (srcX, srcY) location. +dstInfo and (srcX, srcY) offset specifies a source rectangle: +#Code +SkRect srcR; +srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height()); +## + +The source rectangle is intersected with the bounds of the image. If this intersection is not empty, +then we have two sets of pixels (of equal size). Replace dstPixels with the +corresponding Image pixels, performing any Color_Type/Alpha_Type transformations needed +(in the case where Image and dstInfo have different Color_Types or Alpha_Types). +This call can fail, returning false, for several reasons: +if source rectangle does not intersect the image bounds; +if the requested Color_Type/Alpha_Type cannot be converted from the image's types. + +#Param dstInfo incomplete ## +#Param dstPixels incomplete ## +#Param dstRowBytes incomplete ## +#Param srcX incomplete ## +#Param srcY incomplete ## +#Param cachingHint incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY, + CachingHint cachingHint = kAllow_CachingHint) const + +#Param dst incomplete ## +#Param srcX incomplete ## +#Param srcY incomplete ## +#Param cachingHint incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality, + CachingHint cachingHint = kAllow_CachingHint) const + +Copies Image pixels into dst, converting to dst Color_Type and Alpha_Type. +If the conversion cannot be performed, false is returned. +If dst dimensions differ from Image dimensions, Image is scaled, applying +filterQuality. + +#Param dst incomplete ## +#Param filterQuality incomplete ## +#Param cachingHint incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const + +Encode the image's pixels and return the result as SkData. +If the image type cannot be encoded, or the requested encoder format is +not supported, this will return nullptr. + +#Param encodedImageFormat incomplete ## +#Param quality incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkData> encodeToData(SkPixelSerializer* pixelSerializer = nullptr) const + +Encodes Image and returns result as SkData. Will reuse existing encoded data +if present, as returned by refEncodedData. pixelSerializer validates existing +encoded data, and encodes Image when existing encoded data is missing or +invalid. + +Passing nullptr for pixelSerializer selects default serialization which +accepts all data and encodes to PNG. + +Returns nullptr if existing encoded data is missing or invalid and +encoding fails. + +#Param pixelSerializer incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkData> refEncodedData() const + +If the image already has its contents in encoded form (e.g. PNG or JPEG), return that +as SkData. If the image does not already has its contents in encoded form, return nullptr. + +To force the image to return its contents as encoded data, call encodeToData. + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method const char* toString(SkString* string) const + +#Param string incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkImage> makeSubset(const SkIRect& subset) const + +Return a new image that is a subset of this image. The underlying implementation may +share the pixels, or it may make a copy. +If subset does not intersect the bounds of this image, or the copy/share cannot be made, +nullptr will be returned. + +#Param subset incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const + +Ensures that an image is backed by a texture (when GrContext is non-null), suitable for use +with surfaces that have the supplied destination color space. If no transformation is +required, the returned image may be the same as this image. If this image is from a +different GrContext, this will fail. + +#Param context incomplete ## +#Param dstColorSpace incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkImage> makeNonTextureImage() const + +If the image is texture-backed this will make a raster copy of it (or nullptr if reading back +the pixels fails). Otherwise, it returns the original image. + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset, + const SkIRect& clipBounds, SkIRect* outSubset, + SkIPoint* offset) const + +Apply a given image filter to this image, and return the filtered result. +The subset represents the active portion of this image. The return value is similarly an +SkImage, with an active subset (outSubset). This is usually used with texture-backed +images, where the texture may be approx-match and thus larger than the required size. +clipBounds constrains the device-space extent of the image, stored in outSubset. +offset is storage, set to the amount to translate the result when drawn. +If the result image cannot be created, or the result would be transparent black, null +is returned, in which case the offset and outSubset parameters should be ignored by the +caller. + +#Param filter incomplete ## +#Param subset incomplete ## +#Param clipBounds incomplete ## +#Param outSubset incomplete ## +#Param offset incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method size_t getDeferredTextureImageData(const GrContextThreadSafeProxy& contextThreadSafeProxy, + const DeferredTextureImageUsageParams deferredTextureImageUsageParams[], + int paramCnt, + void* buffer, + SkColorSpace* dstColorSpace = nullptr, + SkColorType dstColorType = kN32_SkColorType) const + +This method allows clients to capture the data necessary to turn a SkImage into a texture- +backed image. If the original image is codec-backed this will decode into a format optimized +for the context represented by the proxy. This method is thread safe with respect to the +GrContext whence the proxy came. Clients allocate and manage the storage of the deferred +texture data and control its lifetime. No cleanup is required, thus it is safe to simply free +the memory out from under the data. + +The same method is used both for getting the size necessary for uploading +and retrieving texture data. The deferredTextureImageUsageParams array represents the set of +draws over which to optimize the texture data prior to uploading. + +When called with a null buffer this returns the size that the client must allocate in order +to create deferred texture data for this image (or zero if this is an inappropriate +candidate). The buffer allocated by the client should be 8 byte aligned. +When buffer is not null this fills in the deferred texture data for this image in the +provided buffer (assuming this is an appropriate candidate image and the buffer is +appropriately aligned). Upon success the size written is returned, otherwise 0. +dstColorSpace is the color space of the surface where this texture will ultimately be used. +If the method determines that Mip_Maps are needed, this helps determine the correct strategy +for building them (gamma-correct or not). + +dstColorType is the color type of the surface where this texture will ultimately be used. +This determines the format with which the image will be uploaded to the GPU. If dstColorType +does not support color spaces (low bit depth types such as kARGB_4444_SkColorType), then dstColorSpace +must be null. + +#Param contextThreadSafeProxy incomplete ## +#Param deferredTextureImageUsageParams incomplete ## +#Param paramCnt incomplete ## +#Param buffer incomplete ## +#Param dstColorSpace incomplete ## +#Param dstColorType incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data, + SkBudgeted budgeted) + +Returns a texture-backed image from data produced in SkImage::getDeferredTextureImageData. +The context must be the context that provided the proxy passed to +getDeferredTextureImageData. + +#Param context incomplete ## +#Param data incomplete ## +#Param budgeted incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +#Typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc + +## + +# ------------------------------------------------------------------------------ + +#Method static bool MakeBackendTextureFromSkImage(GrContext* context, + sk_sp<SkImage> image, + GrBackendTexture* backendTexture, + BackendTextureReleaseProc* backendTextureReleaseProc) + +Creates a GrBackendTexture from the provided SkImage. Returns true on success. The +GrBackendTexture and BackendTextureReleaseProc are populated on success. It is the callers +responsibility to call the BackendTextureReleaseProc once they have deleted the texture. +Note that the BackendTextureReleaseProc allows Skia to clean up auxiliary data related +to the GrBackendTexture, and is not a substitute for the client deleting the GrBackendTexture +themselves. + +If image is both texture backed and singly referenced; that is, its only +reference was transferred using std::move(): image is returned in backendTexture +without conversion or making a copy. + +If the SkImage is not texture backed, this function will generate a texture with the image's +contents and return that. + +#Param context incomplete ## +#Param image incomplete ## +#Param backendTexture incomplete ## +#Param backendTextureReleaseProc incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Enum LegacyBitmapMode + +#Code + enum LegacyBitmapMode { + kRO_LegacyBitmapMode, + kRW_LegacyBitmapMode, + }; +## + +Helper functions to convert to SkBitmap + +#Const kRO_LegacyBitmapMode 0 +## +#Const kRW_LegacyBitmapMode 1 +## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Enum ## + +# ------------------------------------------------------------------------------ + +#Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode) const + +Attempt to create a bitmap with the same pixels as the image. The result will always be +a raster-backed bitmap (texture-backed bitmaps are DEPRECATED, and not supported here). +If the mode is kRO_LegacyBitmapMode (read-only), the resulting bitmap will be marked as immutable. +On success, returns true. On failure, returns false and the bitmap parameter will be reset +to empty. + +#Param bitmap incomplete ## +#Param legacyBitmapMode incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isLazyGenerated() const + +Returns true if Image is backed by an image-generator or other service that creates +and caches its pixels or texture on-demand. + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target, + SkTransferFunctionBehavior premulBehavior) const + +If target is supported, returns an SkImage in target color space. +Otherwise, returns nullptr. +This will leave the image as is if it already in target color space. +Otherwise, it will convert the pixels from Image color space to target +color space. If this->colorSpace() is nullptr, Image color space will be +treated as sRGB. + +If premulBehavior is SkTransferFunctionBehavior::kRespect: converts Image +pixels to a linear space before converting to match destination Color_Type +and Color_Space. +If premulBehavior is SkTransferFunctionBehavior::kIgnore: Image +pixels are treated as if they are linear, regardless of how they are encoded. + +#Param target incomplete ## +#Param premulBehavior incomplete ## + +#Return incomplete ## + +#Example +// incomplete +## + +#SeeAlso incomplete + +#Method ## + +#Class SkImage ## + +#Topic Image ## diff --git a/docs/SkMatrix_Reference.bmh b/docs/SkMatrix_Reference.bmh index 107457c5a6..81e95a2d0a 100644 --- a/docs/SkMatrix_Reference.bmh +++ b/docs/SkMatrix_Reference.bmh @@ -34,7 +34,7 @@ improve performance. Matrix is not thread safe unless getType is called first. #Legend ## # operator!=(const SkMatrix& a, const SkMatrix& b) # Returns true if members are unequal. ## # operator==(const SkMatrix& a, const SkMatrix& b) # Returns true if members are equal. ## -# operator[](int index) const # Returns Matrix value. ## +# operator[](int index)_const # Returns Matrix value. ## # operator[](int index) # Returns writable reference to Matrix value. ## #Table ## #Subtopic ## @@ -614,7 +614,7 @@ degenerate forms that collapse to a line or point. Describes that the Matrix makes rendering with and without the matrix are visually alike; a transformed circle remains a circle. Mathematically, this is -referred to as similarity of a Euclidean space, or a similarity transformation. +referred to as similarity of a Euclidean_Space, or a similarity transformation. Preserves right angles, keeping the arms of the angle equal lengths. @@ -821,7 +821,7 @@ vertical translation # ------------------------------------------------------------------------------ -#Method SkScalar operator[](int index) const +#Method SkScalar operator[](int index)_const Returns one matrix value. Asserts if index is out of range and SK_DEBUG is defined. @@ -3412,7 +3412,7 @@ Matrix * src = |D E F| |y| = |Ax+By+Cz Dx+Ey+Fz Gx+Hy+Iz| canvas->translate(128, 128); SkMatrix matrix; matrix.setAll(15, 0, 0, 0, 15, 0, -0.08, 0.04, 1); - matrix.mapHomogeneousPoints(&src[0].fX, &src[0].fX, count); + matrix.mapHomogeneousPoints(src, src, count); debugster(src); ## diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh index e9f568db59..8d3bd604c1 100644 --- a/docs/SkPaint_Reference.bmh +++ b/docs/SkPaint_Reference.bmh @@ -2504,18 +2504,18 @@ the following curve, the pair of curves meet at Stroke_Join. #Example #Height 200 - SkPaint paint;
- paint.setStyle(SkPaint::kStroke_Style);
- paint.setStrokeWidth(20);
- SkPath path;
- path.moveTo(30, 20);
- path.lineTo(40, 40);
- path.conicTo(70, 20, 100, 20, .707f);
- for (SkPaint::Join j : { SkPaint::kMiter_Join, SkPaint::kRound_Join, SkPaint::kBevel_Join } ) {
- paint.setStrokeJoin(j);
- canvas->drawPath(path, paint);
- canvas->translate(0, 70);
- }
+ SkPaint paint; + paint.setStyle(SkPaint::kStroke_Style); + paint.setStrokeWidth(20); + SkPath path; + path.moveTo(30, 20); + path.lineTo(40, 40); + path.conicTo(70, 20, 100, 20, .707f); + for (SkPaint::Join j : { SkPaint::kMiter_Join, SkPaint::kRound_Join, SkPaint::kBevel_Join } ) { + paint.setStrokeJoin(j); + canvas->drawPath(path, paint); + canvas->translate(0, 70); + } ## #Enum Join @@ -3109,7 +3109,8 @@ If Paint has no Path_Effect, the path geometry is unaltered when filled or strok #Example void draw(SkCanvas* canvas) { SkPaint paint1, paint2; - paint1.setPathEffect(SkArcToPathEffect::Make(10)); + SkScalar intervals[] = {1, 2}; + paint1.setPathEffect(SkDashPathEffect::Make(intervals, SK_ARRAY_COUNT(intervals), 10)); SkDebugf("path effect unique: %s\n", paint1.getPathEffect()->unique() ? "true" : "false"); paint2.setPathEffect(paint1.refPathEffect()); SkDebugf("path effect unique: %s\n", paint1.getPathEffect()->unique() ? "true" : "false"); @@ -3476,7 +3477,7 @@ Mask_Filter and Rasterizer. SkRegion region; region.op( 10, 10, 50, 50, SkRegion::kUnion_Op); region.op( 10, 50, 90, 90, SkRegion::kUnion_Op); - paint.setImageFilter(SkImageFilter::MakeBlur(5.0f, 5.0f, nullptr)); + paint.setImageFilter(SkBlurImageFilter::Make(5.0f, 5.0f, nullptr)); canvas->drawRegion(region, paint); paint.setImageFilter(nullptr); paint.setMaskFilter(SkBlurMaskFilter::Make(kNormal_SkBlurStyle, 5)); @@ -3496,7 +3497,7 @@ Mask_Filter and Rasterizer. void draw(SkCanvas* canvas) { SkPaint paint; SkDebugf("nullptr %c= image filter\n", paint.getImageFilter() ? '!' : '='); - paint.setImageFilter(SkImageFilter::MakeBlur(kOuter_SkBlurStyle, 3, nullptr, nullptr)); + paint.setImageFilter(SkBlurImageFilter::Make(kOuter_SkBlurStyle, 3, nullptr, nullptr)); SkDebugf("nullptr %c= image filter\n", paint.getImageFilter() ? '!' : '='); } diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh index 1027a71fee..83943b0b6c 100644 --- a/docs/SkPath_Reference.bmh +++ b/docs/SkPath_Reference.bmh @@ -185,8 +185,8 @@ makes them visible. #Class SkPath Paths contain geometry. Paths may be empty, or contain one or more Verbs that -outline a figure. Path always starts with a move verb to a Cartesian -coordinate, and may be followed by additional verbs that add lines or curves. +outline a figure. Path always starts with a move verb to a Cartesian_Coordinate, +and may be followed by additional verbs that add lines or curves. Adding a close verb makes the geometry into a continuous loop, a closed contour. Paths may contain any number of contours, each beginning with a move verb. @@ -376,8 +376,8 @@ manage Contour, and terminate Path. ## #Const kCubic_Verb 4 Adds 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. + Cubic is a third-order Bezier_Curve section within tangents from Last_Point + to first control Point, and from second control Point to end Point. ## #Const kClose_Verb 5 Closes Contour, connecting Last_Point to kMove_Verb Point. @@ -1609,7 +1609,7 @@ line from (100,100) to (100.0001,100.0001) is not degenerate, exactly #StdOut ## ## -#SeeAlso IsQuadDegenerate IsCubicDegenerate SkPoint::equalsWithinTolerance +#SeeAlso IsQuadDegenerate IsCubicDegenerate ## # ------------------------------------------------------------------------------ @@ -1661,7 +1661,7 @@ quad (1100,1100), (1100,1100), (1100,1100) is degenerate, exactly #StdOut ## ## -#SeeAlso IsLineDegenerate IsCubicDegenerate SkPoint::equalsWithinTolerance +#SeeAlso IsLineDegenerate IsCubicDegenerate ## # ------------------------------------------------------------------------------ @@ -2858,7 +2858,7 @@ void draw(SkCanvas* canvas) { #Alias Cubic_Bezier #Alias Cubic_Beziers -Cubic describes a Bezier curve segment described by a third-order polynomial. +Cubic describes a Bezier_Curve segment described by a third-order polynomial. Cubic begins at a start Point, curving towards the first control Point; and curves from the end Point towards the second control Point. diff --git a/docs/SkPoint_Reference.bmh b/docs/SkPoint_Reference.bmh new file mode 100644 index 0000000000..bac5186f3b --- /dev/null +++ b/docs/SkPoint_Reference.bmh @@ -0,0 +1,1251 @@ +#Topic Point +#Alias Points +#Alias Point_Reference + +#Struct SkPoint + +#Topic Overview + +#Subtopic Subtopics +#ToDo manually add subtopics ## +#Table +#Legend +# topics # description ## +#Legend ## +#Table ## +## + +#Subtopic Operators +#Table +#Legend +# description # function ## +#Legend ## +# SkPoint operator*(SkScalar scale)_const # Returns Point multiplied by scale. ## +# SkPoint operator-()_const # Reverses sign of Point. ## +# SkPoint& operator*=(SkScalar scale) # Multiplies Point by scale factor. ## +# SkPoint operator+(const SkPoint& a, const SkVector& b) # Returns Point offset by Vector. ## +# SkVector operator-(const SkPoint& a, const SkPoint& b) # Returns Vector between Points. ## +# bool operator!=(const SkPoint& a, const SkPoint& b) # Returns true if Point are unequal. ## +# bool operator==(const SkPoint& a, const SkPoint& b) # Returns true if Point are equal. ## +# void operator+=(const SkVector& v) # Adds Vector to Point. ## +# void operator-=(const SkVector& v) # Subtracts Vector from Point. ## +#Table ## +#Subtopic ## + +#Subtopic Member_Functions +#Table +#Legend +# description # function ## +#Legend ## +# CrossProduct # Returns cross product. ## +# Distance # Returns straight-line distance between points. ## +# DotProduct # Returns dot product. ## +# Length # Returns straight-line distance to origin. ## +# Make # Constructs from SkScalar inputs. ## +# Normalize # Sets length to one, and returns prior length. ## +# Offset # Translates Point array. ## +# cross() # Returns cross product. ## +# distanceToOrigin # Returns straight-line distance to origin. ## +# dot() # Returns dot product. ## +# equals() # Returns true if Points are equal. ## +# isFinite # Returns true if no member is infinite or NaN. ## +# isZero # Returns true if both members equal zero. ## +# iset() # Sets to integer input. ## +# length() # Returns straight-line distance to origin. ## +# negate() # Reverses the sign of both members. ## +# normalize() # Sets length to one, preserving direction. ## +# offset() # Translates Point. ## +# scale() # Multiplies Point by scale factor. ## +# set() # Sets to SkScalar input. ## +# setAbs # Sets sign of both members to positive. ## +# setLength # Sets straight-line distance to origin. ## +# setNormalize # Sets length to one, in direction of (x, y). ## +# x() # Returns fX. ## +# y() # Returns fY. ## +#Table ## +#Subtopic ## + +#Topic ## + +#Member SkScalar fX +x-axis value used by both Point and Vector. May contain any value, including +infinities and NaN. +## + +#Member SkScalar fY +y-axis value used by both Point and Vector. May contain any value, including +infinities and NaN. +## + +# ------------------------------------------------------------------------------ + +#Method static constexpr SkPoint Make(SkScalar x, SkScalar y) + +Sets fX to x, fY to y. Used both to set Point and Vector. + +#Param x SkScalar x-axis value of constructed Point or Vector ## +#Param y SkScalar y-axis value of constructed Point or Vector ## + +#Return Point (x, y) ## + +#Example +SkPoint pt1 = {45, 66}; +SkPoint pt2 = SkPoint::Make(45, 66); +SkVector v1 = {45, 66}; +SkVector v2 = SkPoint::Make(45, 66); +SkDebugf("all %s" "equal\n", pt1 == pt2 && pt2 == v1 && v1 == v2 ? "" : "not "); +#StdOut +all equal +## +## + +#SeeAlso set() iset() SkIPoint::Make + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkScalar x() const + +Returns x-axis value of Point or Vector. + +#Return fX ## + +#Example +SkPoint pt1 = {45, 66}; +SkDebugf("pt1.fX %c= pt1.x()\n", pt1.fX == pt1.x() ? '=' : '!'); +#StdOut +pt1.fX == pt1.x() +## +## + +#SeeAlso y() SkIPoint::x() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkScalar y() const + +Returns y-axis value of Point or Vector. + +#Return fY ## + +#Example +SkPoint pt1 = {45, 66}; +SkDebugf("pt1.fY %c= pt1.y()\n", pt1.fY == pt1.y() ? '=' : '!'); +#StdOut +pt1.fY == pt1.y() +## +## + +#SeeAlso x() SkIPoint::y() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isZero() const + +Returns true if fX and fY are both zero. + +#Return true if fX is zero and fY is zero ## + +#Example +SkPoint pt = { 0.f, -0.f};
+SkDebugf("pt.fX=%c%g pt.fY=%c%g\n", std::signbit(pt.fX) ? '-' : '+', fabsf(pt.fX),
+ std::signbit(pt.fY) ? '-' : '+', fabsf(pt.fY));
+SkDebugf("pt.isZero() == %s\n", pt.isZero() ? "true" : "false"); +#StdOut +pt.fX=+0 pt.fY=-0
+pt.isZero() == true +## +## + +#SeeAlso isFinite SkIPoint::isZero + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void set(SkScalar x, SkScalar y) + +Sets fX to x and fY to y. + +#Param x new value for fX ## +#Param y new value for fY ## + +#Example +SkPoint pt1, pt2 = { SK_ScalarPI, SK_ScalarSqrt2 }; +pt1.set(SK_ScalarPI, SK_ScalarSqrt2); +SkDebugf("pt1 %c= pt2\n", pt1 == pt2 ? '=' : '!'); +#StdOut +pt1 == pt2 +## +## + +#SeeAlso iset() Make + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void iset(int32_t x, int32_t y) + +Sets fX to x and fY to y, promoting integers to SkScalar values. + +Assigning a large integer value directly to fX or fY may cause a compiler +error, triggered by narrowing conversion of int to SkScalar. This safely +casts x and y to avoid the error. + +#Param x new value for fX ## +#Param y new value for fY ## + +#Example +SkPoint pt1, pt2 = { SK_MinS16, SK_MaxS16 };
+pt1.iset(SK_MinS16, SK_MaxS16);
+SkDebugf("pt1 %c= pt2\n", pt1 == pt2 ? '=' : '!'); +## + +#SeeAlso set Make SkIPoint::set + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void iset(const SkIPoint& p) + +Sets fX to p.fX and fY to p.fY, promoting integers to SkScalar values. + +Assigning an IPoint containing a large integer value directly to fX or fY may +cause a compiler error, triggered by narrowing conversion of int to SkScalar. +This safely casts p.fX and p.fY to avoid the error. + +#Param p IPoint members promoted to SkScalar ## + +#Example +SkIPoint iPt = { SK_MinS32, SK_MaxS32 };
+SkPoint fPt;
+fPt.iset(iPt);
+SkDebugf("iPt: %d, %d\n", iPt.fX, iPt.fY); +SkDebugf("fPt: %g, %g\n", fPt.fX, fPt.fY); +#StdOut +iPt: -2147483647, 2147483647
+fPt: -2.14748e+09, 2.14748e+09 +## +## + +#SeeAlso set Make SkIPoint::set + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void setAbs(const SkPoint& pt) + +Sets fX to absolute value of pt.fX; and fY to absolute value of pt.fY. + +#Param pt members providing magnitude for fX and fY ## + +#Example +SkPoint test[] = { {0.f, -0.f}, {-1, -2},
+ { SK_ScalarInfinity, SK_ScalarNegativeInfinity },
+ { SK_ScalarNaN, -SK_ScalarNaN } };
+for (const SkPoint& pt : test) {
+ SkPoint absPt;
+ absPt.setAbs(pt);
+ SkDebugf("pt: %g, %g abs: %g, %g\n", pt.fX, pt.fY, absPt.fX, absPt.fY);
+} +#StdOut +pt: 0, -0 abs: 0, 0
+pt: -1, -2 abs: 1, 2
+pt: inf, -inf abs: inf, inf
+pt: nan, -nan abs: nan, nan +## +## + +#SeeAlso set Make negate + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static void Offset(SkPoint points[], int count, const SkVector& offset) + +Adds offset to each Point in points array with count entries. + +#Param points Point array ## +#Param count entries in array ## +#Param offset Vector added to points ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ SkPoint::Offset(points, SK_ARRAY_COUNT(points), { 1, 9 } );
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso offset operator+=(const SkVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static void Offset(SkPoint points[], int count, SkScalar dx, SkScalar dy) + +Adds offset (dx, dy) to each Point in points array of length count. + +#Param points Point array ## +#Param count entries in array ## +#Param dx added to fX in points ## +#Param dy added to fY in points ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ SkPoint::Offset(points, SK_ARRAY_COUNT(points), 1, 9);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso offset operator+=(const SkVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void offset(SkScalar dx, SkScalar dy) + +Adds offset (dx, dy) to Point. + +#Param dx added to fX ## +#Param dy added to fY ## + +#Example +#Height 128 + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ points[1].offset(1, 1);
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso Offset operator+=(const SkVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkScalar length() const + +Returns the Euclidean_Distance from origin, computed as: +#Code +#Literal +sqrt(fX * fX + fY * fY) +## +. + +#Return straight-line distance to origin ## + +#Example +#Height 192 + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint points[] = { { 90, 30 }, { 120, 150 }, { 150, 30 }, { 210, 90 } };
+ const SkPoint origin = {30, 140};
+ for (auto point : points) {
+ canvas->drawLine(origin, point, paint);
+ SkAutoCanvasRestore acr(canvas, true);
+ SkScalar angle = SkScalarATan2((point.fY - origin.fY), point.fX - origin.fX);
+ canvas->rotate(angle * 180 / SK_ScalarPI, origin.fX, origin.fY);
+ SkString length("length = ");
+ length.appendScalar(point.length());
+ canvas->drawString(length, origin.fX + 25, origin.fY - 4, paint);
+ }
+## + +#SeeAlso distanceToOrigin Length setLength Distance + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkScalar distanceToOrigin() const + +Returns the Euclidean_Distance from origin, computed as: +#Code +#Literal +sqrt(fX * fX + fY * fY) +## +. + +#Return straight-line distance to origin ## + +#Example +#Height 192 + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint points[] = { { 60, -110 }, { 90, 10 }, { 120, -110 }, { 180, -50 } };
+ const SkPoint origin = {0, 0};
+ canvas->translate(30, 140);
+ for (auto point : points) {
+ canvas->drawLine(origin, point, paint);
+ SkAutoCanvasRestore acr(canvas, true);
+ SkScalar angle = SkScalarATan2((point.fY - origin.fY), point.fX - origin.fX);
+ canvas->rotate(angle * 180 / SK_ScalarPI, origin.fX, origin.fY);
+ SkString distance("distance = ");
+ distance.appendScalar(point.distanceToOrigin());
+ canvas->drawString(distance, origin.fX + 25, origin.fY - 4, paint);
+ }
+## + +#SeeAlso length Length setLength Distance + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool normalize() + +Scales (fX, fY) so that length() returns one, while preserving ratio of fX to fY, +if possible. If prior length is nearly zero, sets Vector to (0, 0) and returns +false; otherwise returns true. + +#Return true if former length is not zero or nearly zero ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint lines[][2] = { {{ 30, 110 }, { 190, 30 }},
+ {{ 120, 140 }, { 30, 220 }}};
+ for (auto line : lines) {
+ canvas->drawLine(line[0], line[1], paint);
+ SkVector vector = line[1] - line[0];
+ if (vector.normalize()) {
+ SkVector rotate90 = { -vector.fY, vector.fX };
+ rotate90 *= 10.f;
+ canvas->drawLine(line[0] - rotate90, line[0] + rotate90, paint);
+ canvas->drawLine(line[1] - rotate90, line[1] + rotate90, paint);
+ }
+ }
+## + +#SeeAlso Normalize setLength length Length + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool setNormalize(SkScalar x, SkScalar y) + +Sets Vector to (x, y) scaled so length() returns one, and so that +(fX, fY) is proportional to (x, y). If (x, y) length is nearly zero, +sets Vector to (0, 0) and returns false; otherwise returns true. + +#Param x proportional value for fX ## +#Param y proportional value for fY ## + +#Return true if (x, y) length is not zero or nearly zero ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint points[] = { { 60, -110 }, { 90, 10 }, { 120, -110 }, { 180, -50 } };
+ const SkPoint origin = {0, 0};
+ canvas->translate(30, 140);
+ for (auto point : points) {
+ paint.setStrokeWidth(1);
+ paint.setColor(SK_ColorBLACK);
+ canvas->drawLine(origin, point, paint);
+ SkVector normal;
+ normal.setNormalize(point.fX, point.fY);
+ normal *= 100;
+ paint.setStrokeWidth(10);
+ paint.setColor(0x3f4512bf);
+ canvas->drawLine(origin, normal, paint);
+ }
+## + +#SeeAlso normalize setLength + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool setLength(SkScalar length) + +Scales Vector so that distanceToOrigin returns length, if possible. If former +length is nearly zero, sets Vector to (0, 0) and return false; otherwise returns +true. + +#Param length straight-line distance to origin ## + +#Return true if former length is not zero or nearly zero ## + +#Example +#Height 160 + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint points[] = { { 60, -110 }, { 90, 10 }, { 120, -110 }, { 180, -50 } };
+ const SkPoint origin = {0, 0};
+ canvas->translate(30, 140);
+ for (auto point : points) {
+ paint.setStrokeWidth(1);
+ paint.setColor(SK_ColorBLACK);
+ canvas->drawLine(origin, point, paint);
+ SkVector normal = point;
+ normal.setLength(100);
+ paint.setStrokeWidth(10);
+ paint.setColor(0x3f45bf12);
+ canvas->drawLine(origin, normal, paint);
+ }
+## + +#SeeAlso length Length setNormalize setAbs + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool setLength(SkScalar x, SkScalar y, SkScalar length) + +Sets Vector to (x, y) scaled to length, if possible. If former +length is nearly zero, sets Vector to (0, 0) and return false; otherwise returns +true. + +#Param x proportional value for fX ## +#Param y proportional value for fY ## +#Param length straight-line distance to origin ## + +#Return true if (x, y) length is not zero or nearly zero ## + +#Example +#Height 160 + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint points[] = { { 60, -110 }, { 90, 10 }, { 120, -110 }, { 180, -50 } };
+ const SkPoint origin = {0, 0};
+ canvas->translate(30, 140);
+ for (auto point : points) {
+ paint.setStrokeWidth(1);
+ paint.setColor(SK_ColorBLACK);
+ canvas->drawLine(origin, point, paint);
+ SkVector normal;
+ normal.setLength(point.fX, point.fY, 100);
+ paint.setStrokeWidth(10);
+ paint.setColor(0x3fbf4512);
+ canvas->drawLine(origin, normal, paint);
+ }
+## + +#SeeAlso length Length setNormalize setAbs + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void scale(SkScalar scale, SkPoint* dst) const + +Sets dst to Point times scale. dst may be Point to modify Point in place. + +#Param scale factor to multiply Point by ## +#Param dst storage for scaled Point ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint point = {40, -15}, scaled;
+ SkPoint origin = {30, 110};
+ for (auto scale : {1, 2, 3, 5}) {
+ paint.setStrokeWidth(scale * 5);
+ paint.setARGB(0x7f, 0x9f, 0xbf, 0x33 * scale);
+ point.scale(scale, &scaled);
+ canvas->drawLine(origin, origin + scaled, paint);
+ }
+## + +#SeeAlso operator*(SkScalar scale)_const operator*=(SkScalar scale) setLength + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void scale(SkScalar value) + +Scales Point in place by scale. + +#Param value factor to multiply Point by ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint point = {40, -15};
+ SkPoint origin = {30, 110};
+ for (auto scale : {1, 2, 3, 5}) {
+ paint.setStrokeWidth(scale * 5);
+ paint.setARGB(0x7f, 0x9f, 0xbf, 0x33 * scale);
+ point.scale(scale);
+ canvas->drawLine(origin, origin + point, paint);
+ }
+## + +#SeeAlso operator*(SkScalar scale)_const operator*=(SkScalar scale) setLength + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void negate() + +Changes the sign of fX and fY. + +#Example +SkPoint test[] = { {0.f, -0.f}, {-1, -2},
+ { SK_ScalarInfinity, SK_ScalarNegativeInfinity },
+ { SK_ScalarNaN, -SK_ScalarNaN } };
+for (const SkPoint& pt : test) {
+ SkPoint negPt = pt;
+ negPt.negate();
+ SkDebugf("pt: %g, %g negate: %g, %g\n", pt.fX, pt.fY, negPt.fX, negPt.fY);
+} +#StdOut +pt: 0, -0 negate: -0, 0
+pt: -1, -2 negate: 1, 2
+pt: inf, -inf negate: -inf, inf
+pt: nan, -nan negate: -nan, nan +## +## + +#SeeAlso operator-()_const setAbs + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkPoint operator-()_const + +Returns Point changing the signs of fX and fY. + +#Return Point as (-fX, -fY) ## + +#Example +SkPoint test[] = { {0.f, -0.f}, {-1, -2},
+ { SK_ScalarInfinity, SK_ScalarNegativeInfinity },
+ { SK_ScalarNaN, -SK_ScalarNaN } };
+for (const SkPoint& pt : test) {
+ SkPoint negPt = -pt;
+ SkDebugf("pt: %g, %g negate: %g, %g\n", pt.fX, pt.fY, negPt.fX, negPt.fY);
+} +#StdOut +pt: 0, -0 negate: -0, 0
+pt: -1, -2 negate: 1, 2
+pt: inf, -inf negate: -inf, inf
+pt: nan, -nan negate: -nan, nan +## +## + +#SeeAlso negate operator-(const SkPoint& a, const SkPoint& b) operator-=(const SkVector& v) SkIPoint::operator-()_const + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void operator+=(const SkVector& v) + +Adds Vector v to Point. Sets Point to: +#Formula +(fX + v.fX, fY + v.fY) +## +. + +#Param v Vector to add ## + +#Example +#Height 128 + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ points[1] += {1, 1};
+ points[2] += {-1, -1};
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso offset() operator+(const SkPoint& a, const SkVector& b) SkIPoint::operator+=(const SkIVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void operator-=(const SkVector& v) + +Subtracts Vector v from Point. Sets Point to: +#Formula +(fX - v.fX, fY - v.fY) +## +. + +#Param v Vector to subtract ## + +#Example +#Height 128 + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ points[1] -= {1, 1};
+ points[2] -= {-1, -1};
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso offset() operator-(const SkPoint& a, const SkPoint& b) SkIPoint::operator-=(const SkIVector& v) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkPoint operator*(SkScalar scale)_const + +Returns Point multiplied by scale. + +#Param scale Scalar to multiply by ## + +#Return Point as (fX * scale, fY * scale) ## + +#Example +#Height 128 + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(15, 10);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ for (auto& point : points) {
+ point = point * 1.5f;
+ }
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso operator*=(SkScalar scale) scale() setLength setNormalize + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkPoint& operator*=(SkScalar scale) + +Multiplies Point by scale. Sets Point to: +#Formula +(fX * scale, fY * scale) +## + +#Param scale Scalar to multiply by ## + +#Return reference to Point ## + +#Example +#Height 128 + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(15, 10);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ for (auto& point : points) {
+ point *= 2;
+ }
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso operator*(SkScalar scale)_const scale() setLength setNormalize + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool isFinite() const + +Returns true if both fX and fY are measurable values. + +#Return true for values other than infinities and NaN ## + +#Example +SkPoint test[] = { {0, -0.f}, {-1, -2}, {SK_ScalarInfinity, 1}, {SK_ScalarNaN, -1} };
+for (const SkPoint& pt : test) {
+ SkDebugf("pt: %g, %g finite: %s\n", pt.fX, pt.fY, pt.isFinite() ? "true" : "false");
+} +#StdOut +pt: 0, -0 finite: true
+pt: -1, -2 finite: true
+pt: inf, 1 finite: false
+pt: nan, -1 finite: false +## +## + +#SeeAlso SkRect::isFinite SkPath::isFinite + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool equals(SkScalar x, SkScalar y) const + +Returns true if Point is equivalent to Point constructed from (x, y). + +#Param x value compared with fX ## +#Param y value compared with fY ## + +#Return true if Point equals (x, y) ## + +#Example +SkPoint test[] = { {0, -0.f}, {-1, -2}, {SK_ScalarInfinity, 1}, {SK_ScalarNaN, -1} };
+for (const SkPoint& pt : test) {
+ SkDebugf("pt: %g, %g %c= pt\n", pt.fX, pt.fY, pt.equals(pt.fX, pt.fY) ? '=' : '!');
+} +#StdOut +pt: 0, -0 == pt
+pt: -1, -2 == pt
+pt: inf, 1 == pt
+pt: nan, -1 != pt +## +## + +#SeeAlso operator==(const SkPoint& a, const SkPoint& b) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool operator==(const SkPoint& a, const SkPoint& b) + +Returns true if a is equivalent to b. + +#Param a Point to compare ## +#Param b Point to compare ## + +#Return true if a.fX == b.fX and a.fY == b.fY ## + +#Example +SkPoint test[] = { {0, -0.f}, {-1, -2}, {SK_ScalarInfinity, 1}, {SK_ScalarNaN, -1} };
+for (const SkPoint& pt : test) {
+ SkDebugf("pt: %g, %g %c= pt\n", pt.fX, pt.fY, pt == pt ? '=' : '!');
+} +#StdOut +pt: 0, -0 == pt
+pt: -1, -2 == pt
+pt: inf, 1 == pt
+pt: nan, -1 != pt +## +## + +#SeeAlso equals() operator!=(const SkPoint& a, const SkPoint& b) + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool operator!=(const SkPoint& a, const SkPoint& b) + +Returns true if a is not equivalent to b. + +#Param a Point to compare ## +#Param b Point to compare ## + +#Return true if a.fX != b.fX or a.fY != b.fY ## + +#Example +SkPoint test[] = { {0, -0.f}, {-1, -2}, {SK_ScalarInfinity, 1}, {SK_ScalarNaN, -1} };
+for (const SkPoint& pt : test) {
+ SkDebugf("pt: %g, %g %c= pt\n", pt.fX, pt.fY, pt != pt ? '!' : '=');
+} +#StdOut +pt: 0, -0 == pt
+pt: -1, -2 == pt
+pt: inf, 1 == pt
+pt: nan, -1 != pt +## +## + +#SeeAlso operator==(const SkPoint& a, const SkPoint& b) equals() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkVector operator-(const SkPoint& a, const SkPoint& b) + +Returns Vector from b to a, computed as +#Formula +(a.fX - b.fX, a.fY - b.fY) +## +. + +Can also be used to subtract Vector from Point, returning Point. +Can also be used to subtract Vector from Vector, returning Vector. + +#Param a Point to subtract from ## +#Param b Point to subtract ## + +#Return Vector from b to a ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ points[1] += points[0] - points[2];
+ points[2] -= points[3] - points[5];
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso operator-=(const SkVector& v) offset() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkPoint operator+(const SkPoint& a, const SkVector& b) + +Returns Point resulting from Point a offset by Vector b, computed as: +#Formula +(a.fX + b.fX, a.fY + b.fY) +## +. + +Can also be used to offset Point b by Vector a, returning Point. +Can also be used to add Vector to Vector, returning Vector. + +#Param a Point or Vector to add to ## +#Param b Point or Vector to add ## + +#Return Point equal to a offset by b ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkPoint points[] = { { 3, 1 }, { 4, 2 }, { 5, 1 }, { 7, 3 },
+ { 6, 4 }, { 7, 5 }, { 5, 7 },
+ { 4, 6 }, { 3, 7 }, { 1, 5 },
+ { 2, 4 }, { 1, 3 }, { 3, 1 } };
+ canvas->scale(30, 15);
+ paint.setStyle(SkPaint::kStroke_Style);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+ SkVector mod = {1, 1};
+ for (auto& point : points) {
+ point = point + mod;
+ mod.fX *= 1.1f;
+ mod.fY += .2f;
+ }
+ paint.setColor(SK_ColorRED);
+ canvas->drawPoints(SkCanvas::kPolygon_PointMode, SK_ARRAY_COUNT(points), points, paint);
+## + +#SeeAlso operator+=(const SkVector& v) offset() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static SkScalar Length(SkScalar x, SkScalar y) + +Returns the Euclidean_Distance from origin, computed as: +#Code +#Literal +sqrt(x * x + y * y) +## +. + +#Param x component of length ## +#Param y component of length ## + +#Return straight-line distance to origin ## + +#Example +#Height 192 + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint points[] = { { 90, 30 }, { 120, 150 }, { 150, 30 }, { 210, 90 } };
+ const SkPoint origin = {30, 140};
+ for (auto point : points) {
+ canvas->drawLine(origin, point, paint);
+ SkAutoCanvasRestore acr(canvas, true);
+ SkScalar angle = SkScalarATan2((point.fY - origin.fY), point.fX - origin.fX);
+ canvas->rotate(angle * 180 / SK_ScalarPI, origin.fX, origin.fY);
+ SkString length("length = ");
+ length.appendScalar(SkPoint::Length(point.fX, point.fY));
+ canvas->drawString(length, origin.fX + 25, origin.fY - 4, paint);
+ }
+## + +#SeeAlso length() Distance setLength + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static SkScalar Normalize(SkVector* vec) + +Scales (vec->fX, vec->fY) so that length() returns one, while preserving ratio of vec->fX to vec->fY, +if possible. If original length is nearly zero, sets vec to (0, 0) and returns zero; +otherwise, returns length of vec before vec is scaled. + +Returned prior length may be SK_ScalarInfinity if it can not be represented by SkScalar. + +Note that normalize() is faster if prior length is not required. + +#Param vec normalized to unit length ## + +#Return original vec length ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint lines[][2] = { {{ 30, 110 }, { 190, 30 }},
+ {{ 30, 220 }, { 120, 140 }}};
+ for (auto line : lines) {
+ canvas->drawLine(line[0], line[1], paint);
+ SkVector vector = line[1] - line[0];
+ SkScalar priorLength = SkPoint::Normalize(&vector);
+ SkVector rotate90 = { -vector.fY, vector.fX };
+ rotate90 *= 10.f;
+ canvas->drawLine(line[0] - rotate90, line[0] + rotate90, paint);
+ canvas->drawLine(line[1] - rotate90, line[1] + rotate90, paint);
+ SkString length("length = ");
+ length.appendScalar(priorLength);
+ canvas->drawString(length, line[0].fX + 25, line[0].fY - 4, paint);
+ }
+## + +#SeeAlso normalize() setLength Length + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static SkScalar Distance(const SkPoint& a, const SkPoint& b) + +Returns the Euclidean_Distance between a and b. + +#Param a line end point ## +#Param b line end point ## + +#Return straight-line distance from a to b ## + +#Example +#Height 192 + SkPaint paint;
+ paint.setAntiAlias(true);
+ const SkPoint lines[][2] = {{{-10, -10}, {90, 30}}, {{0, 0}, {150, 30}}, {{10, 25}, {120, 150}}};
+ const SkPoint origin = {30, 160};
+ for (auto line : lines) {
+ SkPoint a = origin + line[0];
+ const SkPoint& b = line[1];
+ canvas->drawLine(a, b, paint);
+ SkAutoCanvasRestore acr(canvas, true);
+ SkScalar angle = SkScalarATan2((b.fY - a.fY), b.fX - a.fX);
+ canvas->rotate(angle * 180 / SK_ScalarPI, a.fX, a.fY);
+ SkString distance("distance = ");
+ distance.appendScalar(SkPoint::Distance(a, b));
+ canvas->drawString(distance, a.fX + 25, a.fY - 4, paint);
+ }
+## + +#SeeAlso length() setLength + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static SkScalar DotProduct(const SkVector& a, const SkVector& b) + +Returns the dot product of Vector a and Vector b. + +#Param a left side of dot product ## +#Param b right side of dot product ## + +#Return product of input magnitudes and cosine of the angle between them ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkVector vectors[][2] = {{{50, 2}, {-14, 20}}, {{0, 50}, {-50, 0}}, {{-20, 25}, {25, -20}},
+ {{-20, -24}, {-24, -20}}};
+ SkPoint center[] = {{32, 32}, {160, 32}, {32, 160}, {160, 160}};
+ paint.setStrokeWidth(2);
+ for (size_t i = 0; i < 4; ++i) {
+ canvas->drawLine(center[i], center[i] + vectors[i][0], paint);
+ canvas->drawLine(center[i], center[i] + vectors[i][1], paint);
+ SkString str;
+ str.printf("dot = %g", SkPoint::DotProduct(vectors[i][0], vectors[i][1]));
+ canvas->drawString(str, center[i].fX, center[i].fY, paint);
+ }
+## + +#SeeAlso dot CrossProduct + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static SkScalar CrossProduct(const SkVector& a, const SkVector& b) + +Returns the cross product of Vector a and Vector b. + +a and b form three-dimensional vectors with z equal to zero. The cross product +is a three-dimensional vector with x and y equal to zero. The cross product z +term equals the returned value. + +#Param a left side of cross product ## +#Param b right side of cross product ## + +#Return area spanned by Vectors signed by angle direction ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkVector vectors[][2] = {{{50, 2}, {-14, 20}}, {{0, 50}, {-50, 0}}, {{-20, 25}, {25, -20}},
+ {{-20, -24}, {-24, -20}}};
+ SkPoint center[] = {{32, 32}, {160, 32}, {32, 160}, {160, 160}};
+ paint.setStrokeWidth(2);
+ for (size_t i = 0; i < 4; ++i) {
+ paint.setColor(SK_ColorRED);
+ canvas->drawLine(center[i], center[i] + vectors[i][0], paint);
+ paint.setColor(SK_ColorBLUE);
+ canvas->drawLine(center[i], center[i] + vectors[i][1], paint);
+ SkString str;
+ SkScalar cross = SkPoint::CrossProduct(vectors[i][1], vectors[i][0]);
+ str.printf("cross = %g", cross);
+ paint.setColor(cross >= 0 ? SK_ColorRED : SK_ColorBLUE);
+ canvas->drawString(str, center[i].fX, center[i].fY, paint);
+ }
+## + +#SeeAlso cross DotProduct + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkScalar cross(const SkVector& vec) const + +Returns the cross product of Vector and vec. + +Vector and vec form three-dimensional vectors with z equal to zero. The +cross product is a three-dimensional vector with x and y equal to zero. +The cross product z term equals the returned value. + +#Param vec right side of cross product ## + +#Return area spanned by Vectors signed by angle direction ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkVector vectors[][2] = {{{50, 2}, {-14, 20}}, {{0, 50}, {-50, 0}}, {{-20, 25}, {25, -20}},
+ {{-20, -24}, {-24, -20}}};
+ SkPoint center[] = {{32, 32}, {160, 32}, {32, 160}, {160, 160}};
+ paint.setStrokeWidth(2);
+ for (size_t i = 0; i < 4; ++i) {
+ paint.setColor(SK_ColorRED);
+ canvas->drawLine(center[i], center[i] + vectors[i][0], paint);
+ paint.setColor(SK_ColorBLUE);
+ canvas->drawLine(center[i], center[i] + vectors[i][1], paint);
+ SkString str;
+ SkScalar cross = vectors[i][0].cross(vectors[i][1]);
+ str.printf("cross = %g", cross);
+ paint.setColor(cross >= 0 ? SK_ColorRED : SK_ColorBLUE);
+ canvas->drawString(str, center[i].fX, center[i].fY, paint);
+ }
+## + +#SeeAlso CrossProduct dot + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkScalar dot(const SkVector& vec) const + +Returns the dot product of Vector and Vector vec. + +#Param vec right side of dot product ## + +#Return product of input magnitudes and cosine of the angle between them ## + +#Example + SkPaint paint;
+ paint.setAntiAlias(true);
+ SkVector vectors[][2] = {{{50, 2}, {-14, 20}}, {{0, 50}, {-50, 0}}, {{-20, 25}, {25, -20}},
+ {{-20, -24}, {-24, -20}}};
+ SkPoint center[] = {{32, 32}, {160, 32}, {32, 160}, {160, 160}};
+ paint.setStrokeWidth(2);
+ for (size_t i = 0; i < 4; ++i) {
+ canvas->drawLine(center[i], center[i] + vectors[i][0], paint);
+ canvas->drawLine(center[i], center[i] + vectors[i][1], paint);
+ SkString str;
+ str.printf("dot = %g", vectors[i][0].dot(vectors[i][1]));
+ canvas->drawString(str, center[i].fX, center[i].fY, paint);
+ }
+## + +#SeeAlso DotProduct cross + +#Method ## + +#Struct SkPoint ## + +#Topic Point ## + +# ------------------------------------------------------------------------------ + +#Topic Vector + #Alias Vectors + #Typedef SkPoint SkVector + #Typedef ## +## diff --git a/docs/SkRect_Reference.bmh b/docs/SkRect_Reference.bmh index 1a28f1bd12..d803c9373a 100644 --- a/docs/SkRect_Reference.bmh +++ b/docs/SkRect_Reference.bmh @@ -30,8 +30,8 @@ integer input cannot convert to SkScalar without loss of precision. #Legend # description # function ## #Legend ## -# bool operator!=(const SkRect& a, const SkRect& b) # Returns true if member bits are unequal. ## -# bool operator==(const SkRect& a, const SkRect& b) # Returns true if member bits are equal. ## +# bool operator!=(const SkRect& a, const SkRect& b) # Returns true if members are unequal. ## +# bool operator==(const SkRect& a, const SkRect& b) # Returns true if members are equal. ## #Table ## #Subtopic ## diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh new file mode 100644 index 0000000000..c6cbbbb7aa --- /dev/null +++ b/docs/SkSurface_Reference.bmh @@ -0,0 +1,1601 @@ +#Topic Surface +#Alias Surface_Reference + +#Class SkSurface + +SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be +allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface). +SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call +surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface). +SkSurface always has non-zero dimensions. If there is a request for a new surface, and either +of the requested dimensions are zero, then nullptr will be returned. + +#Topic Overview + +#Subtopic Subtopics +#ToDo manually add subtopics ## +#Table +#Legend +# topics # description ## +#Legend ## +#Table ## +## + +#Subtopic Member_Functions +#Table +#Legend +# description # function ## +#Legend ## +# MakeFromBackendRenderTarget # Creates Surface from GPU memory buffer. ## +# MakeFromBackendTexture # Creates Surface from GPU-backed texture. ## +# MakeFromBackendTextureAsRenderTarget # Creates Surface from GPU-backed texture. ## +# MakeNull # Creates Surface without backing pixels. ## +# MakeRaster # Creates Surface from SkImageInfo. ## +# MakeRasterDirect # Creates Surface from SkImageInfo and Pixel_Storage. ## +# MakeRasterDirectReleaseProc # Creates Surface from SkImageInfo and Pixel_Storage. ## +# MakeRasterN32Premul # Creates Surface from width, height matching output. ## +# MakeRenderTarget # Creates Surface pointing to new GPU memory buffer. ## +# characterize() # Set up Surface_Characterization for threaded pre-processing. ## +# draw() # Draws Surface contents to canvas. ## +# flush() # Resolve pending I/O. ## +# flushAndSignalSemaphores # Resolve pending I/O, and signal. ## +# generationID # Returns unique ID. ## +# getCanvas # Returns Canvas that draws into Surface. ## +# getRenderTargetHandle # Returns the GPU reference to render target. ## +# getTextureHandle # Returns the GPU reference to texture. ## +# height() # Returns pixel row count. ## +# makeImageSnapshot # Returns Image capturing Surface contents. ## +# makeSurface # Returns a compatible Surface. ## +# notifyContentWillChange # Notifies that contents will be changed outside of Skia. ## +# peekPixels # Copies Surface parameters to Pixmap. ## +# prepareForExternalIO # To be deprecated. ## +# props() # Returns Surface_Properties. ## +# readPixels # Copies Rect of pixels. ## +# wait() # Pause commands until signaled. ## +# width() # Returns pixel column count. ## +#Table ## +#Subtopic ## + +#Topic ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels, + size_t rowBytes, + const SkSurfaceProps* surfaceProps = nullptr) + +Allocates raster Surface. Canvas returned by Surface draws directly into pixels. + +Surface is returned if all parameters are valid. +Valid parameters include: +info dimensions are greater than zero; +info contains Image_Color_Type and Image_Alpha_Type supported by Raster_Surface; +pixels is not nullptr; +rowBytes is large enough to contain info width pixels of Image_Color_Type. + +Pixel buffer size should be info height times computed rowBytes. +Pixels are not initialized. +To access pixels after drawing, call flush() or peekPixels. + +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Raster_Surface; width and height must be greater than zero +## +#Param pixels pointer to destination pixels buffer ## +#Param rowBytes interval from one Surface row to the next ## +#Param surfaceProps LCD striping orientation and setting for device independent fonts; + may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +void draw(SkCanvas* ) { + SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3); + const size_t size = info.computeMinByteSize(); + SkAutoTMalloc<SkPMColor> storage(size); + SkPMColor* pixels = storage.get(); + sk_sp<SkSurface> surface(SkSurface::MakeRasterDirect(info, pixels, info.minRowBytes())); + SkCanvas* canvas = surface->getCanvas(); + canvas->clear(SK_ColorWHITE); + SkPMColor pmWhite = pixels[0]; + SkPaint paint; + canvas->drawPoint(1, 1, paint); + canvas->flush(); // ensure that point was drawn + for (int y = 0; y < info.height(); ++y) { + for (int x = 0; x < info.width(); ++x) { + SkDebugf("%c", *pixels++ == pmWhite ? '-' : 'x'); + } + SkDebugf("\n"); + } +} + #StdOut + --- + -x- + --- + ## +## + +#SeeAlso MakeRasterDirectReleaseProc MakeRaster MakeRasterN32Premul SkCanvas::MakeRasterDirect + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels, + size_t rowBytes, + void (*releaseProc)(void* pixels, void* context), + void* context, const SkSurfaceProps* surfaceProps = nullptr) + +Allocates raster Surface. Canvas returned by Surface draws directly into pixels. +releaseProc is called with pixels and context when Surface is deleted. + +Surface is returned if all parameters are valid. +Valid parameters include: +info dimensions are greater than zero; +info contains Image_Color_Type and Image_Alpha_Type supported by Raster_Surface; +pixels is not nullptr; +rowBytes is large enough to contain info width pixels of Image_Color_Type. + +Pixel buffer size should be info height times computed rowBytes. +Pixels are not initialized. +To access pixels after drawing, call flush() or peekPixels. + +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Raster_Surface; width and height must be greater than zero +## +#Param pixels pointer to destination pixels buffer ## +#Param rowBytes interval from one Surface row to the next ## +#Param releaseProc called when Surface is deleted; may be nullptr ## +#Param context passed to releaseProc; may be nullptr ## +#Param surfaceProps LCD striping orientation and setting for device independent fonts; + may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +#Function +static void release_direct_surface_storage(void* pixels, void* context) { + if (pixels == context) { + SkDebugf("expected release context\n"); + } + sk_free(pixels); +} + +## +void draw(SkCanvas* ) { + SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3); + const size_t rowBytes = info.minRowBytes(); + void* pixels = sk_malloc_throw(info.computeByteSize(rowBytes)); + sk_sp<SkSurface> surface(SkSurface::MakeRasterDirectReleaseProc(info, pixels, rowBytes, + release_direct_surface_storage, pixels)); + SkCanvas* canvas = surface->getCanvas(); + canvas->clear(SK_ColorWHITE); + SkPMColor* colorPtr = (SkPMColor*) pixels; + SkPMColor pmWhite = colorPtr[0]; + SkPaint paint; + canvas->drawPoint(1, 1, paint); + canvas->flush(); // ensure that point was drawn + for (int y = 0; y < info.height(); ++y) { + for (int x = 0; x < info.width(); ++x) { + SkDebugf("%c", *colorPtr++ == pmWhite ? '-' : 'x'); + } + SkDebugf("\n"); + } +} +#StdOut +--- +-x- +--- +expected release context +## +## + +#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRaster + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes, + const SkSurfaceProps* surfaceProps) + +Allocates raster Surface. Canvas returned by Surface draws directly into pixels. +Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times +rowBytes, or times imageInfo.minRowBytes() if rowBytes is zero. +Pixel memory is deleted when Surface is deleted. + +Surface is returned if all parameters are valid. +Valid parameters include: +info dimensions are greater than zero; +info contains Image_Color_Type and Image_Alpha_Type supported by Raster_Surface; +rowBytes is large enough to contain info width pixels of Image_Color_Type, or is zero. + +If rowBytes is not zero, subsequent images returned by makeImageSnapshot +have the same rowBytes. + +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Raster_Surface; width and height must be greater than zero +## +#Param rowBytes interval from one Surface row to the next; may be zero ## +#Param surfaceProps LCD striping orientation and setting for device independent fonts; + may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +void draw(SkCanvas* ) { + SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3); + const size_t rowBytes = 64; + sk_sp<SkSurface> surface(SkSurface::MakeRaster(info, rowBytes, nullptr)); + SkCanvas* canvas = surface->getCanvas(); + canvas->clear(SK_ColorWHITE); + SkPixmap pixmap; + if (surface->peekPixels(&pixmap)) { + const uint32_t* colorPtr = pixmap.addr32(); + SkPMColor pmWhite = colorPtr[0]; + SkPaint paint; + canvas->drawPoint(1, 1, paint); + canvas->flush(); // ensure that point was drawn + for (int y = 0; y < info.height(); ++y) { + for (int x = 0; x < info.width(); ++x) { + SkDebugf("%c", colorPtr[x] == pmWhite ? '-' : 'x'); + } + colorPtr += rowBytes / sizeof(colorPtr[0]); + SkDebugf("\n"); + } + } +} +#StdOut +--- +-x- +--- +## +## + +#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRasterDirectReleaseProc + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, + const SkSurfaceProps* props = nullptr) + +Allocates raster Surface. Canvas returned by Surface draws directly into pixels. +Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times +imageInfo.minRowBytes(). +Pixel memory is deleted when Surface is deleted. + +Surface is returned if all parameters are valid. +Valid parameters include: +info dimensions are greater than zero; +info contains Image_Color_Type and Image_Alpha_Type supported by Raster_Surface. + +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Raster_Surface; width and height must be greater than zero +## +#Param props LCD striping orientation and setting for device independent fonts; + may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +void draw(SkCanvas* ) { + SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3); + sk_sp<SkSurface> surface(SkSurface::MakeRaster(info)); + SkCanvas* canvas = surface->getCanvas(); + canvas->clear(SK_ColorWHITE); + SkPixmap pixmap; + if (surface->peekPixels(&pixmap)) { + const uint32_t* colorPtr = pixmap.addr32(); + SkPMColor pmWhite = colorPtr[0]; + SkPaint paint; + canvas->drawPoint(1, 1, paint); + canvas->flush(); // ensure that point was drawn + for (int y = 0; y < info.height(); ++y) { + for (int x = 0; x < info.width(); ++x) { + SkDebugf("%c", colorPtr[x] == pmWhite ? '-' : 'x'); + } + colorPtr += info.width(); + SkDebugf("\n"); + } + } +} +## + +#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRasterDirectReleaseProc + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height, + const SkSurfaceProps* surfaceProps = nullptr) + +Allocates raster Surface. Canvas returned by Surface draws directly into pixels. +Allocates and zeroes pixel memory. Pixel memory size is height times width times +four. Pixel memory is deleted when Surface is deleted. + +Internally, sets Image_Info to width, height, Native_Color_Type, and +kPremul_SkAlphaType. + +Surface is returned if width and height are greater than zero. + +Use to create Surface that matches SkPMColor, the native pixel arrangement on +the platform. Surface drawn to output device skips converting its pixel format. + +#Param width pixel column count; must be greater than zero ## +#Param height pixel row count; must be greater than zero ## +#Param surfaceProps LCD striping orientation and setting for device independent + fonts; may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +void draw(SkCanvas* ) { + sk_sp<SkSurface> surface(SkSurface::MakeRasterN32Premul(3, 3)); + SkCanvas* canvas = surface->getCanvas(); + canvas->clear(SK_ColorWHITE); + SkPixmap pixmap; + if (surface->peekPixels(&pixmap)) { + const uint32_t* colorPtr = pixmap.addr32(); + SkPMColor pmWhite = colorPtr[0]; + SkPaint paint; + canvas->drawPoint(1, 1, paint); + canvas->flush(); // ensure that point was drawn + for (int y = 0; y < surface->height(); ++y) { + for (int x = 0; x < surface->width(); ++x) { + SkDebugf("%c", colorPtr[x] == pmWhite ? '-' : 'x'); + } + colorPtr += surface->width(); + SkDebugf("\n"); + } + } +} +#StdOut +--- +-x- +--- +## +## + +#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRasterDirectReleaseProc + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context, + const GrBackendTexture& backendTexture, + GrSurfaceOrigin origin, int sampleCnt, + sk_sp<SkColorSpace> colorSpace, + const SkSurfaceProps* surfaceProps) + +Wraps a GPU-backed texture into Surface. Caller must ensure the texture is +valid for the lifetime of returned Surface. If sampleCnt greater than zero, +creates an intermediate MSAA Surface which is used for drawing backendTexture. + +Surface is returned if all parameters are valid. backendTexture is valid if +its pixel configuration agrees with colorSpace and context; for instance, if +backendTexture has an sRGB configuration, then context must support sRGB, +and colorSpace must be present. Further, backendTexture width and height must +not exceed context capabilities, and the context must be able to support +back-end textures. + +If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr. + +#Param context GPU_Context ## +#Param backendTexture texture residing on GPU ## +#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## +#Param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing ## +#Param colorSpace range of colors ## +#Param surfaceProps LCD striping orientation and setting for device independent + fonts; may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +#ToDo remove !fiddle below once backEndTextureRenderTarget is available ## +#Platform !fiddle gpu cpu + SkPaint paint; + paint.setTextSize(32); + GrContext* context = canvas->getGrContext(); + if (!context) { + canvas->drawString("GPU only!", 20, 40, paint); + return; + } + sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTexture(context, + backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0, nullptr, nullptr); + auto surfaceCanvas = gpuSurface->getCanvas(); + surfaceCanvas->clear(SK_ColorWHITE); + surfaceCanvas->drawString("GPU rocks!", 20, 40, paint); + sk_sp<SkImage> image(gpuSurface->makeImageSnapshot()); + canvas->drawImage(image, 0, 0); +## + +#SeeAlso GrBackendTexture MakeFromBackendRenderTarget MakeRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context, + const GrBackendRenderTarget& backendRenderTarget, + GrSurfaceOrigin origin, + sk_sp<SkColorSpace> colorSpace, + const SkSurfaceProps* surfaceProps) + +Wraps a GPU-backed buffer into Surface. Caller must ensure render target is +valid for the lifetime of returned Surface. + +Surface is returned if all parameters are valid. backendRenderTarget is valid if +its pixel configuration agrees with colorSpace and context; for instance, if +backendRenderTarget has an sRGB configuration, then context must support sRGB, +and colorSpace must be present. Further, backendRenderTarget width and height must +not exceed context capabilities, and the context must be able to support +back-end render targets. + +If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr. + +#Param context GPU_Context ## +#Param backendRenderTarget GPU intermediate memory buffer ## +#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## +#Param colorSpace range of colors ## +#Param surfaceProps LCD striping orientation and setting for device independent + fonts; may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +#ToDo remove !fiddle below once backEndTextureRenderTarget is available ## +#Platform !fiddle gpu + SkPaint paint; + paint.setTextSize(32); + GrContext* context = canvas->getGrContext(); + if (!context) { + canvas->drawString("GPU only!", 20, 40, paint); + return; + } + sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendRenderTarget(context, + backEndRenderTarget, kTopLeft_GrSurfaceOrigin, nullptr, nullptr); + auto surfaceCanvas = gpuSurface->getCanvas(); + surfaceCanvas->clear(SK_ColorWHITE); + surfaceCanvas->drawString("GPU rocks!", 20, 40, paint); + sk_sp<SkImage> image(gpuSurface->makeImageSnapshot()); + canvas->drawImage(image, 0, 0); +## + +#SeeAlso MakeFromBackendTexture MakeRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context, + const GrBackendTexture& backendTexture, + GrSurfaceOrigin origin, + int sampleCnt, + sk_sp<SkColorSpace> colorSpace, + const SkSurfaceProps* surfaceProps) + +Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as +a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own +the associated render target objects (but not the provided texture). Skia will not assume +ownership of the texture and the client must ensure the texture is valid for the lifetime +of the SkSurface. + +If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr. + +#Param context GPU_Context ## +#Param backendTexture texture residing on GPU ## +#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## +#Param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing ## +#Param colorSpace range of colors ## +#Param surfaceProps LCD striping orientation and setting for device independent + fonts; may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +#Platform !fiddle gpu + SkPaint paint; + paint.setTextSize(32); + GrContext* context = canvas->getGrContext(); + if (!context) { + canvas->drawString("GPU only!", 20, 40, paint); + return; + } + sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTextureAsRenderTarget( + context, backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0, + nullptr, nullptr); + auto surfaceCanvas = gpuSurface->getCanvas(); + surfaceCanvas->clear(SK_ColorWHITE); + surfaceCanvas->drawString("GPU rocks!", 20, 40, paint); + sk_sp<SkImage> image(gpuSurface->makeImageSnapshot()); + canvas->drawImage(image, 0, 0); +## + +#SeeAlso MakeFromBackendRenderTarget MakeRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted, + const SkImageInfo& imageInfo, + int sampleCount, GrSurfaceOrigin surfaceOrigin, + const SkSurfaceProps* surfaceProps, + bool shouldCreateWithMips = false) + +Returns offscreen Surface on GPU indicated by context. Allocates memory for +pixels, based on the width, height, and Image_Color_Type in ImageInfo. budgeted +selects whether allocation for offscreen pixels is tracked by context. imageInfo +describes the pixel format in Image_Color_Type, and transparency in +Image_Alpha_Type, and color matching in Color_Space. + +sampleCount requests the number of samples per pixel. +Pass zero to disable Multi_Sample_Anti_Aliasing. The request is rounded +up to the next supported count, or rounded down if it is larger than the +maximum supported count. + +surfaceOrigin pins either the top-left or the bottom-left corner to the origin. + +shouldCreateWithMips hints that Image returned by makeImageSnapshot is Mip_Map. + +If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr. + +#Param context GPU_Context ## +#Param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes ## +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space; + width, or height, or both, may be zero +## +#Param sampleCount samples per pixel, or 0 to disable full scene anti-aliasing ## +#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## +#Param surfaceProps LCD striping orientation and setting for device independent + fonts; may be nullptr +## +#Param shouldCreateWithMips hint that Surface will host Mip_Map images ## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#ToDo not sure that this example is relevant; surfaceOrigin doesn't appear to do anything ## +#Example +#Platform gpu +#Height 64 + SkPaint paint; + paint.setTextSize(32); + GrContext* context = canvas->getGrContext(); + if (!context) { + canvas->drawString("GPU only!", 20, 40, paint); + return; + } + SkImageInfo info = SkImageInfo::MakeN32(256, 64, kOpaque_SkAlphaType); + for (auto surfaceOrigin : { kTopLeft_GrSurfaceOrigin, kBottomLeft_GrSurfaceOrigin } ) { + auto gpuSurface(SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, info, 0, + surfaceOrigin, nullptr)); + auto surfaceCanvas = gpuSurface->getCanvas(); + surfaceCanvas->clear(SK_ColorWHITE); + surfaceCanvas->drawString("GPU rocks!", 20, 40, paint); + sk_sp<SkImage> image(gpuSurface->makeImageSnapshot()); + canvas->drawImage(image, 0, 0); + canvas->translate(0, 128); + } +## + +#SeeAlso MakeFromBackendRenderTarget MakeFromBackendTextureAsRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted, + const SkImageInfo& imageInfo, int sampleCount, + const SkSurfaceProps* props) + +Returns offscreen Surface on GPU indicated by context. Allocates memory for +pixels, based on the width, height, and Image_Color_Type in ImageInfo. budgeted +selects whether allocation for offscreen pixels is tracked by context. imageInfo +describes the pixel format in Image_Color_Type, and transparency in +Image_Alpha_Type, and color matching in Color_Space. + +sampleCount requests the number of samples per pixel. +Pass zero to disable Multi_Sample_Anti_Aliasing. The request is rounded +up to the next supported count, or rounded down if it is larger than the +maximum supported count. + +Surface bottom-left corner is pinned to the origin. + +#Param context GPU_Context ## +#Param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes ## +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Raster_Surface; width, or height, or both, may be zero +## +#Param sampleCount samples per pixel, or 0 to disable Multi_Sample_Anti_Aliasing ## +#Param props LCD striping orientation and setting for device independent + fonts; may be nullptr +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +#Description +LCD text takes advantage of raster striping to improve resolution. Only one of +the four combinations is correct, depending on whether the monitor's LCD is +horizontal or vertical, and whether the order of the stripes is red blue green +or red green blue. +## +void draw(SkCanvas* canvas) { + auto test_draw = [](SkCanvas* surfaceCanvas) -> void { + SkPaint paint; + paint.setAntiAlias(true); + paint.setLCDRenderText(true); + paint.setColor(0xFFBBBBBB); + surfaceCanvas->drawRect(SkRect::MakeWH(128, 64), paint); + paint.setColor(SK_ColorWHITE); + paint.setTextSize(32); + surfaceCanvas->drawString("Pest", 0, 25, paint); + }; + GrContext* context = canvas->getGrContext(); + SkImageInfo info = SkImageInfo::MakeN32(128, 64, kOpaque_SkAlphaType); + SkAutoTMalloc<SkPMColor> storage(info.computeMinByteSize()); + SkBitmap bitmap; + bitmap.installPixels(info, storage.get(), info.minRowBytes()); + int y = 0; + for (auto geometry : { kRGB_H_SkPixelGeometry, kBGR_H_SkPixelGeometry, + kRGB_V_SkPixelGeometry, kBGR_V_SkPixelGeometry } ) { + SkSurfaceProps props(0, geometry); + std::unique_ptr<SkCanvas> offscreen = SkCanvas::MakeRasterDirect(info, storage.get(), + info.minRowBytes(), &props); + sk_sp<SkSurface> surface = context ? SkSurface::MakeRenderTarget( + context, SkBudgeted::kNo, info, 0, &props) : SkSurface::MakeRaster(info, &props); + test_draw(surface->getCanvas()); + surface->draw(canvas, 0, y, nullptr); + surface->draw(offscreen.get(), 0, 0, nullptr); + SkAutoCanvasRestore acr(canvas, true); + canvas->scale(8, 8); + canvas->drawBitmap(bitmap, 12, y / 8); + y += 64; + } +} +## + +#SeeAlso MakeFromBackendRenderTarget MakeFromBackendTextureAsRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted, + const SkImageInfo& imageInfo) + +Returns offscreen Surface on GPU indicated by context. Allocates memory for +pixels, based on the width, height, and Image_Color_Type in ImageInfo. budgeted +selects whether allocation for offscreen pixels is tracked by context. imageInfo +describes the pixel format in Image_Color_Type, and transparency in +Image_Alpha_Type, and color matching in Color_Space. + +Surface bottom-left corner is pinned to the origin. + +#Param context GPU_Context ## +#Param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes ## +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Raster_Surface; width, or height, or both, may be zero +## + +#Return Surface if all parameters are valid; otherwise, nullptr ## + +#Example +#Platform gpu + SkPaint paint; + paint.setTextSize(32); + GrContext* context = canvas->getGrContext(); + if (!context) { + canvas->drawString("GPU only!", 20, 40, paint); + return; + } + SkImageInfo info = SkImageInfo::MakeN32(256, 64, kOpaque_SkAlphaType); + auto gpuSurface(SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, info)); + auto surfaceCanvas = gpuSurface->getCanvas(); + surfaceCanvas->clear(SK_ColorWHITE); + surfaceCanvas->drawString("GPU rocks!", 20, 40, paint); + sk_sp<SkImage> image(gpuSurface->makeImageSnapshot()); + canvas->drawImage(image, 0, 0); +## + +#SeeAlso MakeFromBackendRenderTarget MakeFromBackendTextureAsRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method static sk_sp<SkSurface> MakeNull(int width, int height) + +Returns Surface without backing pixels. Drawing to Canvas returned from Surface +has no effect. Calling makeImageSnapshot() on returned Surface returns nullptr. + +#Param width one or greater ## +#Param height one or greater ## + +#Return Surface if width and height are positive; otherwise, nullptr ## + +#Example + SkDebugf("SkSurface::MakeNull(0, 0) %c= nullptr\n", SkSurface::MakeNull(0, 0) == nullptr ? + '=' : '!'); + const int w = 37; + const int h = 1000; + auto surf = SkSurface::MakeNull(w, h); + auto nullCanvas = surf->getCanvas(); + nullCanvas->drawPaint(SkPaint()); // does not crash, nothing draws + SkDebugf("surf->makeImageSnapshot() %c= nullptr\n", surf->makeImageSnapshot() == nullptr ? + '=' : '!'); +#StdOut +SkSurface::MakeNull(0, 0) == nullptr +surf->makeImageSnapshot() == nullptr +## +## + +#SeeAlso MakeRaster MakeRenderTarget + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int width() const + +Returns pixel count in each row; may be zero or greater. + +#Return number of pixel columns ## + +#Example + const int width = 37; + const int height = 1000; + auto surf = SkSurface::MakeNull(width, height); + auto nullCanvas = surf->getCanvas(); + SkDebugf("surface width=%d canvas width=%d\n", surf->width(), + nullCanvas->getBaseLayerSize().fWidth); +#StdOut +surface width=37 canvas width=37 +## +## + +#SeeAlso height() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method int height() const + +Returns pixel row count; may be zero or greater. + +#Return number of pixel rows ## + +#Example + const int width = 37; + const int height = 1000; + auto surf = SkSurface::MakeNull(width, height); + auto nullCanvas = surf->getCanvas(); + SkDebugf("surface height=%d canvas height=%d\n", surf->height(), + nullCanvas->getBaseLayerSize().fHeight); +#StdOut +surface height=1000 canvas height=1000 +## +## + +#SeeAlso width() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method uint32_t generationID() + +Returns unique value identifying the content of Surface. Returned value changes +each time the content changes. Content is changed by drawing, or by calling +notifyContentWillChange. + +#Return unique content identifier ## + +#Example + auto surface = SkSurface::MakeRasterN32Premul(1, 1); + for (int i = 0; i < 3; ++i) { + SkDebugf("surface generationID: %d\n", surface->generationID()); + if (0 == i) { + surface->getCanvas()->drawColor(SK_ColorBLACK); + } else { + surface->notifyContentWillChange(SkSurface::kDiscard_ContentChangeMode); + } + } +#StdOut +surface generationID: 1 +surface generationID: 2 +surface generationID: 3 +## +## + +#SeeAlso notifyContentWillChange ContentChangeMode getCanvas + +#Method ## + +# ------------------------------------------------------------------------------ + +#Enum ContentChangeMode + +#Code + enum ContentChangeMode { + kDiscard_ContentChangeMode, + kRetain_ContentChangeMode, + }; +## + +ContentChangeMode members are parameters to notifyContentWillChange. + +#Const kDiscard_ContentChangeMode +Pass to notifyContentWillChange to discard surface contents when +the surface is cleared or overwritten. +## +#Const kRetain_ContentChangeMode +Pass to notifyContentWillChange when to preserve surface contents. +If a snapshot has been generated, this copies the Surface contents. +## + +#SeeAlso notifyContentWillChange generationID + +#Enum ## + +# ------------------------------------------------------------------------------ + +#Method void notifyContentWillChange(ContentChangeMode mode) + +Notifies that Surface contents will be changed by code outside of Skia. +Subsequent calls to generationID return a different value. + +mode is normally passed as kRetain_ContentChangeMode. + +#Private +CAN WE DEPRECATE THIS? +## + +#Param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode ## + +#Example + auto surface = SkSurface::MakeRasterN32Premul(1, 1); + for (int i = 0; i < 3; ++i) { + SkDebugf("surface generationID: %d\n", surface->generationID()); + if (0 == i) { + surface->getCanvas()->drawColor(SK_ColorBLACK); + } else { + surface->notifyContentWillChange(SkSurface::kDiscard_ContentChangeMode); + } + } +## + +#SeeAlso ContentChangeMode generationID + +#Method ## + +# ------------------------------------------------------------------------------ + +#Enum BackendHandleAccess + +#Code + enum BackendHandleAccess { + kFlushRead_BackendHandleAccess, + kFlushWrite_BackendHandleAccess, + kDiscardWrite_BackendHandleAccess, + }; +## + +#Const kFlushRead_BackendHandleAccess +Caller may read from the back-end object. +## +#Const kFlushWrite_BackendHandleAccess +Caller may write to the back-end object. +## +#Const kDiscardWrite_BackendHandleAccess +Caller must overwrite the entire back-end object. +## + +#Example +#Platform gpu + SkPaint paint;
+ paint.setTextSize(32);
+ GrContext* context = canvas->getGrContext();
+ if (!context) {
+ canvas->drawString("GPU only!", 20, 40, paint);
+ return;
+ }
+ sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+ context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
+ int y = 20;
+ SkString str;
+ paint.setTextSize(16);
+ for (auto access : { SkSurface::kFlushRead_BackendHandleAccess,
+ SkSurface::kFlushWrite_BackendHandleAccess,
+ SkSurface::kDiscardWrite_BackendHandleAccess } ) {
+ sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+ str.printf("uniqueID=%d", image->uniqueID());
+ canvas->drawString(str, 20, y += 20, paint);
+ GrBackendObject backendObject = gpuSurface->getTextureHandle(access);
+ str.printf("backendObject %c= 0", backendObject != 0 ? '!' : '=');
+ canvas->drawString(str, 20, y += 20, paint);
+ }
+ sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+ str.printf("final image uniqueID=%d", image->uniqueID());
+ canvas->drawString(str, 20, y += 20, paint);
+## + +#SeeAlso getTextureHandle getRenderTargetHandle + +#Enum ## + +# ------------------------------------------------------------------------------ + +#Method GrBackendObject getTextureHandle(BackendHandleAccess backendHandleAccess) + +Returns the GPU back-end reference of the texture used by Surface, or zero +if Surface is not backed by a GPU texture. + +The returned texture handle is only valid until the next draw into Surface, +or when Surface is deleted. + +#Param backendHandleAccess one of: kFlushRead_BackendHandleAccess, + kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess +## + +#Return GPU texture reference ## + +#Example +#Platform gpu +#Height 64 + SkPaint paint;
+ paint.setTextSize(32);
+ GrContext* context = canvas->getGrContext();
+ if (!context) {
+ canvas->drawString("GPU only!", 20, 40, paint);
+ return;
+ }
+ sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+ context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
+ GrBackendObject backendObject = gpuSurface->getTextureHandle(
+ SkSurface::kFlushRead_BackendHandleAccess);
+ if (backendObject) {
+ SkString str;
+ str.printf("backendObject=%08x", backendObject);
+ paint.setTextSize(16);
+ canvas->drawString(str, 20, 40, paint);
+ }
+## + +#SeeAlso getRenderTargetHandle GrBackendObject BackendHandleAccess + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool getRenderTargetHandle(GrBackendObject* backendObject, + BackendHandleAccess backendHandleAccess) + +Returns true and stores the GPU back-end reference of the render target used +by Surface in backendObject. + +Return false if Surface is not backed by a GPU render target, and leaves +backendObject unchanged. + +The returned render target handle is only valid until the next draw into Surface, +or when Surface is deleted. + +In OpenGL this returns the frame buffer object ID. + +#Param backendObject GPU intermediate memory buffer ## +#Param backendHandleAccess one of: kFlushRead_BackendHandleAccess, + kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess +## + +#Return true if Surface is backed by GPU texture ## + +#Example +#Platform gpu +#Height 64 + SkPaint paint;
+ paint.setTextSize(32);
+ GrContext* context = canvas->getGrContext();
+ if (!context) {
+ canvas->drawString("GPU only!", 20, 40, paint);
+ return;
+ }
+ sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+ context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
+ GrBackendObject backendObject;
+ if (gpuSurface->getRenderTargetHandle(&backendObject,
+ SkSurface::kFlushRead_BackendHandleAccess)) {
+ SkString str;
+ str.printf("backendObject=%d", backendObject);
+ paint.setTextSize(16);
+ canvas->drawString(str, 20, 40, paint);
+ }
+## + +#SeeAlso getTextureHandle GrBackendObject BackendHandleAccess + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method SkCanvas* getCanvas() + +Returns Canvas that draws into Surface. Subsequent calls return the same Canvas. +Canvas returned is managed and owned by Surface, and is deleted when Surface +is deleted. + +#Return drawing Canvas for Surface ## + +#Example +#Height 64 + sk_sp<SkSurface> surface(SkSurface::MakeRasterN32Premul(64, 64)); + SkCanvas* surfaceCanvas = surface->getCanvas(); + surfaceCanvas->clear(SK_ColorBLUE); + SkPaint paint; + paint.setTextSize(40); + surfaceCanvas->drawString("\xF0\x9F\x98\x81", 12, 45, paint); + surface->draw(canvas, 0, 0, nullptr); +## + +#SeeAlso makeSurface makeImageSnapshot draw() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo) + +Returns a compatible Surface, or nullptr. Returned Surface contains +the same raster, GPU, or null properties as the original. Returned Surface +does not share the same pixels. + +Returns nullptr if imageInfo width or height are zero, or if imageInfo +is incompatible with Surface. + +#Param imageInfo width, height, Image_Color_Type, Image_Alpha_Type, Color_Space, + of Surface; width and height must be greater than zero +## + +#Return compatible Surface or nullptr ## + +#Example +#Height 96 + sk_sp<SkSurface> big(SkSurface::MakeRasterN32Premul(64, 64)); + sk_sp<SkSurface> lil(big->makeSurface(SkImageInfo::MakeN32(32, 32, kPremul_SkAlphaType))); + big->getCanvas()->clear(SK_ColorRED); + lil->getCanvas()->clear(SK_ColorBLACK); + SkPixmap pixmap; + if (big->peekPixels(&pixmap)) { + SkBitmap bigBits; + bigBits.installPixels(pixmap); + canvas->drawBitmap(bigBits, 0, 0); + } + if (lil->peekPixels(&pixmap)) { + SkBitmap lilBits; + lilBits.installPixels(pixmap); + canvas->drawBitmap(lilBits, 64, 64); + } +## + +#SeeAlso makeImageSnapshot getCanvas draw() + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method sk_sp<SkImage> makeImageSnapshot() + +Returns Image capturing Surface contents. Subsequent drawing to Surface contents +are not captured. Image allocation is accounted for if Surface was created with +SkBudgeted::kYes. + +#Return Image initialized with Surface contents ## + +#Example +#Height 64 + sk_sp<SkSurface> big(SkSurface::MakeRasterN32Premul(64, 64)); + sk_sp<SkSurface> lil(big->makeSurface(SkImageInfo::MakeN32(32, 32, kPremul_SkAlphaType))); + big->getCanvas()->clear(SK_ColorRED); + lil->getCanvas()->clear(SK_ColorBLACK); + sk_sp<SkImage> early(big->makeImageSnapshot()); + lil->draw(big->getCanvas(), 16, 16, nullptr); + sk_sp<SkImage> later(big->makeImageSnapshot()); + canvas->drawImage(early, 0, 0); + canvas->drawImage(later, 128, 0); +## + +#SeeAlso draw getCanvas + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint) + +Draws Surface contents to canvas, with its top-left corner at (x, y). + +If Paint paint is not nullptr, apply Color_Filter, Color_Alpha, Image_Filter, +Blend_Mode, and Draw_Looper. + +#Param canvas Canvas drawn into ## +#Param x horizontal offset in Canvas ## +#Param y vertical offset in Canvas ## +#Param paint Paint containing Blend_Mode, Color_Filter, Image_Filter, + and so on; or nullptr +## + +#Example +#Height 64 + sk_sp<SkSurface> big(SkSurface::MakeRasterN32Premul(64, 64)); + sk_sp<SkSurface> lil(big->makeSurface(SkImageInfo::MakeN32(32, 32, kPremul_SkAlphaType))); + big->getCanvas()->clear(SK_ColorRED); + lil->getCanvas()->clear(SK_ColorBLACK); + lil->draw(big->getCanvas(), 16, 16, nullptr); + SkPixmap pixmap; + if (big->peekPixels(&pixmap)) { + SkBitmap bigBits; + bigBits.installPixels(pixmap); + canvas->drawBitmap(bigBits, 0, 0); + } +## + +#SeeAlso makeImageSnapshot getCanvas + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool peekPixels(SkPixmap* pixmap) + +Copies Surface pixel address, row bytes, and Image_Info to Pixmap, if address +is available, and returns true. If pixel address is not available, return +false and leave Pixmap unchanged. + +pixmap contents become invalid on any future change to Surface. + +#Param pixmap storage for pixel state if pixels are readable; otherwise, ignored ## + +#Return true if Surface has direct access to pixels ## + +#Example +#Height 64 + sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64)); + auto surfCanvas = surf->getCanvas(); + surfCanvas->clear(SK_ColorRED); + SkPaint paint; + paint.setTextSize(40); + surfCanvas->drawString("&", 16, 48, paint); + SkPixmap pixmap; + if (surf->peekPixels(&pixmap)) { + SkBitmap surfBits; + surfBits.installPixels(pixmap); + canvas->drawBitmap(surfBits, 0, 0); + } +## + +#SeeAlso readPixels + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY) + +Copies Rect of pixels to dst. + +Source Rect corners are (srcX, srcY) and (this->width(), this->height()). +Destination Rect corners are (0, 0) and (dst.width(), dst.height()). +Copies each readable pixel intersecting both rectangles, without scaling, +converting to dst.colorType() and dst.alphaType() if required. + +Pixels are readable when Surface is raster, or backed by a GPU. + +The destination pixel storage must be allocated by the caller. + +Pixel values are converted only if Image_Color_Type and Image_Alpha_Type +do not match. Only pixels within both source and destination rectangles +are copied. dst contents outside Rect intersection are unchanged. + +Pass negative values for srcX or srcY to offset pixels across or down destination. + +Does not copy, and returns false if: + +#List +# Source and destination rectangles do not intersect. ## +# Pixmap pixels could not be allocated. ## +# dst.rowBytes() is too small to contain one row of pixels. ## +## + +#Param dst storage for pixels copied from Surface ## +#Param srcX offset into readable pixels in x; may be negative ## +#Param srcY offset into readable pixels in y; may be negative ## + +#Return true if pixels were copied ## + +#Example +#Height 32 + sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64)); + auto surfCanvas = surf->getCanvas(); + surfCanvas->clear(SK_ColorRED); + SkPaint paint; + paint.setTextSize(40); + surfCanvas->drawString("&", 0, 32, paint); + std::vector<SkPMColor> storage; + storage.resize(surf->width() * surf->height()); + SkPixmap pixmap(SkImageInfo::MakeN32Premul(32, 32), &storage.front(), + surf->width() * sizeof(storage[0])); + if (surf->readPixels(pixmap, 0, 0)) { + SkBitmap surfBits; + surfBits.installPixels(pixmap); + canvas->drawBitmap(surfBits, 0, 0); + } +## + +#SeeAlso peekPixels + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, + int srcX, int srcY) + +Copies Rect of pixels from Canvas into dstPixels. + +Source Rect corners are (srcX, srcY) and (this->width(), this->height()). +Destination Rect corners are (0, 0) and (dstInfo.width(), dstInfo.height()). +Copies each readable pixel intersecting both rectangles, without scaling, +converting to dstInfo.colorType() and dstInfo.alphaType() if required. + +Pixels are readable when Surface is raster, or backed by a GPU. + +The destination pixel storage must be allocated by the caller. + +Pixel values are converted only if Image_Color_Type and Image_Alpha_Type +do not match. Only pixels within both source and destination rectangles +are copied. dstPixels contents outside Rect intersection are unchanged. + +Pass negative values for srcX or srcY to offset pixels across or down destination. + +Does not copy, and returns false if: + +#List +# Source and destination rectangles do not intersect. ## +# Surface pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType(). ## +# dstRowBytes is too small to contain one row of pixels. ## +## + +#Param dstInfo width, height, Image_Color_Type, and Image_Alpha_Type of dstPixels ## +#Param dstPixels storage for pixels; dstInfo.height() times dstRowBytes, or larger ## +#Param dstRowBytes size of one destination row; dstInfo.width() times pixel size, or larger ## +#Param srcX offset into readable pixels in x; may be negative ## +#Param srcY offset into readable pixels in y; may be negative ## + +#Return true if pixels were copied ## + +#Example +#Height 64 +#Description + A black oval drawn on a red background provides an image to copy. + readPixels copies one quarter of the Surface into each of the four corners. + The copied quarter ovals overdraw the original oval. +## + sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64)); + auto surfCanvas = surf->getCanvas(); + surfCanvas->clear(SK_ColorRED); + SkPaint paint; + surfCanvas->drawOval({4, 8, 58, 54}, paint); + SkImageInfo info = SkImageInfo::Make(64, 64, kBGRA_8888_SkColorType, kPremul_SkAlphaType); + sk_sp<SkData> data(SkData::MakeUninitialized(info.minRowBytes() * info.height())); + sk_bzero(data->writable_data(), info.minRowBytes() * info.height()); + for (int x : { 32, -32 } ) { + for (int y : { 32, -32 } ) { + surf->readPixels(info, data->writable_data(), info.minRowBytes(), x, y); + } + } + sk_sp<SkImage> image = SkImage::MakeRasterData(info, data, info.minRowBytes()); + canvas->drawImage(image, 0, 0); +## + +#SeeAlso peekPixels + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool readPixels(const SkBitmap& dst, int srcX, int srcY) + +Copies Rect of pixels from Surface into bitmap. + +Source Rect corners are (srcX, srcY) and (this->width(), this->height()). +Destination Rect corners are (0, 0) and (bitmap.width(), bitmap.height()). +Copies each readable pixel intersecting both rectangles, without scaling, +converting to bitmap.colorType() and bitmap.alphaType() if required. + +Pixels are readable when Surface is raster, or backed by a GPU. + +The destination pixel storage must be allocated by the caller. + +Pixel values are converted only if Image_Color_Type and Image_Alpha_Type +do not match. Only pixels within both source and destination rectangles +are copied. dst contents outside Rect intersection are unchanged. + +Pass negative values for srcX or srcY to offset pixels across or down destination. + +Does not copy, and returns false if: + +#List +# Source and destination rectangles do not intersect. ## +# Surface pixels could not be converted to dst.colorType() or dst.alphaType(). ## +# dst pixels could not be allocated. ## +# dst.rowBytes() is too small to contain one row of pixels. ## +## + +#Param dst storage for pixels copied from Surface ## +#Param srcX offset into readable pixels in x; may be negative ## +#Param srcY offset into readable pixels in y; may be negative ## + +#Return true if pixels were copied ## + +#Example + sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
+ auto surfCanvas = surf->getCanvas();
+ surfCanvas->clear(SK_ColorGREEN);
+ SkPaint paint;
+ surfCanvas->drawOval({2, 10, 58, 54}, paint);
+ SkImageInfo info = SkImageInfo::Make(64, 64, kBGRA_8888_SkColorType, kPremul_SkAlphaType);
+ SkBitmap bitmap;
+ bitmap.setInfo(info);
+ bitmap.allocPixels();
+ for (int x : { 32, -32 } ) {
+ for (int y : { 32, -32 } ) {
+ surf->readPixels(bitmap, x, y);
+ }
+ }
+ canvas->drawBitmap(bitmap, 0, 0);
+## + +#SeeAlso peekPixels + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method const SkSurfaceProps& props() const + +Returns Surface_Properties for surface. + +#Return LCD striping orientation and setting for device independent fonts ## + +#Example + const char* names[] = { "Unknown", "RGB_H", "BGR_H", "RGB_V", "BGR_V" }; + sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
+ SkDebugf("surf.props(): k%s_SkPixelGeometry\n", names[surf->props().pixelGeometry()]); +#StdOut +surf.props(): kRGB_H_SkPixelGeometry +## +## + +#SeeAlso SkSurfaceProps + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void prepareForExternalIO() + +To be deprecated. + +#NoExample +## + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void flush() + +Issues pending Surface commands to the GPU-backed API and resolves any Surface MSAA. + +Skia flushes as needed, so it is not necessary to call this if Skia manages +drawing and object lifetime. Call when interleaving Skia calls with native +GPU calls. + +#NoExample +## + +#SeeAlso GrBackendSemaphore + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores, + GrBackendSemaphore signalSemaphores[]) + +Issues pending Surface commands to the GPU-backed API and resolves any Surface MSAA. +After issuing all commands, signalSemaphores of count numSemaphores semaphores +are signaled by the GPU. + +For each GrBackendSemaphore in signalSemaphores: +if GrBackendSemaphore is initialized, the GPU back-end uses the semaphore as is; +otherwise, a new semaphore is created and initializes GrBackendSemaphore. + +The caller must delete the semaphores created and returned in signalSemaphores. +GrBackendSemaphore can be deleted as soon as this function returns. + +If the back-end API is OpenGL only uninitialized GrBackendSemaphores are supported. + +If the back-end API is Vulkan semaphores may be initialized or uninitialized. +If uninitialized, created semaphores are valid only with the VkDevice +with which they were created. + +If GrSemaphoresSubmitted::kNo is returned, the GPU back-end did not create or +add any semaphores to signal on the GPU; the caller should not instruct the GPU +to wait on any of the semaphores. + +Pending surface commands are flushed regardless of the return result. + +#Param numSemaphores size of signalSemaphores array ## +#Param signalSemaphores array of semaphore containers ## + +#Return one of: GrSemaphoresSubmitted::kYes, GrSemaphoresSubmitted::kNo ## + +#NoExample +## + +#SeeAlso wait GrBackendSemaphore + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores) + +Inserts a list of GPU semaphores that the current GPU-backed API must wait on before +executing any more commands on the GPU for this surface. Skia will take ownership of the +underlying semaphores and delete them once they have been signaled and waited on. +If this call returns false, then the GPU back-end will not wait on any passed in semaphores, +and the client will still own the semaphores. + +#Param numSemaphores size of waitSemaphores array ## +#Param waitSemaphores array of semaphore containers ## + +#Return true if GPU is waiting on semaphores ## + +#Example +#ToDo this is copy and paste silliness masquerading as an example. Probably need gpu + globals and definitely need gpu expertise to make a real example out of this + ## +#Platform !fiddle gpu +#Height 64 + SkPaint paint;
+ paint.setTextSize(32);
+ GrContext* context = canvas->getGrContext();
+ if (!context) {
+ canvas->drawString("GPU only!", 20, 40, paint);
+ return;
+ }
+ GrBackendSemaphore semaphore; + sk_sp<SkSurface> surface = SkSurface::MakeRenderTarget(
+ context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));
+ surface->flushAndSignalSemaphores(1, &semaphore); + sk_sp<SkImage> image = surface->makeImageSnapshot(); + GrBackendObject backendImage = image->getTextureHandle(false); // unused + SkASSERT(backendImage); + const SkImageInfo childImageInfo = SkImageInfo::Make(64, 64, + kRGBA_8888_SkColorType, kPremul_SkAlphaType); + sk_sp<SkSurface> childSurface(SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, + childImageInfo, 0, kTopLeft_GrSurfaceOrigin, nullptr)); + GrBackendTexture backendTexture; + sk_sp<SkImage> childImage = SkImage::MakeFromTexture(context, + backendTexture, // undefined + kTopLeft_GrSurfaceOrigin, kPremul_SkAlphaType, nullptr); + SkCanvas* childCanvas = childSurface->getCanvas(); + childCanvas->clear(SK_ColorRED); + childSurface->wait(1, &semaphore); + childCanvas->drawImage(childImage, 32, 0); + childSurface->draw(canvas, 0, 0, nullptr);
+## + +#SeeAlso flushAndSignalSemaphores GrBackendSemaphore + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method bool characterize(SkSurfaceCharacterization* characterization) const + +Initializes Surface_Characterization that can be used to perform GPU back-end +pre-processing in a separate thread. Typically this is used to divide drawing +into multiple tiles. DeferredDisplayListRecorder records the drawing commands +for each tile. + +Return true if Surface supports characterization. Raster_Surface returns false. + +#Param characterization properties for parallel drawing ## + +#Return true if supported ## + +#Example +#Platform gpu +#Height 64 + SkPaint paint;
+ paint.setTextSize(32);
+ GrContext* context = canvas->getGrContext();
+ if (!context) {
+ canvas->drawString("GPU only!", 20, 40, paint);
+ return;
+ }
+ sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+ context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));
+ SkSurfaceCharacterization characterization;
+ if (!gpuSurface->characterize(&characterization)) {
+ canvas->drawString("characterization unsupported", 20, 40, paint);
+ return;
+ }
+ // start of threadable work
+ SkDeferredDisplayListRecorder recorder(characterization);
+ SkCanvas* subCanvas = recorder.getCanvas();
+ subCanvas->clear(SK_ColorGREEN);
+ std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();
+ // end of threadable work
+ gpuSurface->draw(displayList.get());
+ sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();
+ canvas->drawImage(std::move(img), 0, 0);
+## + +#SeeAlso draw() SkSurfaceCharacterization SkDeferredDisplayList + +#Method ## + +# ------------------------------------------------------------------------------ + +#Method void draw(SkDeferredDisplayList* deferredDisplayList) + +Draws deferred display list created using SkDeferredDisplayListRecorder. +The draw has no effect if Surface_Characterization stored in deferredDisplayList +is not compatible with Surface. + +#Param deferredDisplayList drawing commands ## + +#Example +#Height 64 +#Platform gpu cpu + SkPaint paint;
+ paint.setTextSize(16);
+ sk_sp<SkSurface> gpuSurface = SkSurface::MakeRasterN32Premul(64, 64);
+ SkSurfaceCharacterization characterization;
+ if (!gpuSurface->characterize(&characterization)) {
+ canvas->drawString("characterization unsupported", 20, 40, paint);
+ return;
+ }
+ // start of threadable work
+ SkDeferredDisplayListRecorder recorder(characterization);
+ SkCanvas* subCanvas = recorder.getCanvas();
+ subCanvas->clear(SK_ColorGREEN);
+ std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();
+ // end of threadable work
+ gpuSurface->draw(displayList.get());
+ sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();
+ canvas->drawImage(std::move(img), 0, 0);
+## + +#SeeAlso characterize() SkSurfaceCharacterization SkDeferredDisplayList + +#Method ## + +#Class SkSurface ## + +#Topic Surface ## diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh index 8cb21282a0..4163b43e89 100644 --- a/docs/undocumented.bmh +++ b/docs/undocumented.bmh @@ -1,19 +1,18 @@ # external references that will be documented eventually ... #External - DirectWrite TrueType Windows Linux Android iOS + DirectWrite TrueType Windows Linux Android iOS __ANDROID_API__ FreeType FreeType-based Harfbuzz Descenders Kerning Unhinted - LCD RGB + LCD RGB sRGB Unicode Unicode5 UTF-8 UTF-16 UTF-32 ASCII Unichar API CPU - GPU GPU-backed OpenGL Vulkan + GPU GPU-backed OpenGL Vulkan I/O MSAA UV_Mapping Multi_Sample_Anti_Aliasing PDF XPS RFC NaN NaNs - Bezier Coons Cartesian Euclidean + Bezier_Curve Coons_Patch Cartesian_Coordinate Euclidean_Distance Euclidean_Space C C++ Destructor Subclasses - SaveLayerFlags # not external; need to add typedef support SkUserConfig # not external, but still thinking about how markup refers to this SkXXX.h # ditto SkXXX_Reference # ditto @@ -26,6 +25,7 @@ SK_SUPPORT_LEGACY_PAINT_TEXTDECORATION # ditto SK_BUILD_FOR_ANDROID_FRAMEWORK # ditto SK_IGNORE_TO_STRING # ditto + SK_SUPPORT_GPU # ditto # FreeType related FT_LOAD_TARGET_LIGHT @@ -51,6 +51,12 @@ FT_Load_Glyph #Alias Arcs #Topic ## +#Topic Backend_Semaphore +#Class GrBackendSemaphore +#Alias GrBackendSemaphores +## +## + #Topic BBH_Factory #Class SkBBHFactory ## @@ -81,7 +87,10 @@ FT_Load_Glyph ## #Topic Color - #Typedef SkColor + #Typedef uint32_t SkColor + #Typedef ## + + #Typedef uint32_t SkPMColor #Typedef ## # fixme: defines, not methods, need new markup type @@ -174,6 +183,8 @@ FT_Load_Glyph ## #Topic Data +#Class SkData +## ## #Topic Debugging @@ -181,6 +192,15 @@ FT_Load_Glyph ## ## +#Topic Deferred_Display_List +#Class SkDeferredDisplayList +## +#Subtopic Recorder +#Class SkDeferredDisplayListRecorder +## +## +## + #Topic Device #Class SkBaseDevice ## @@ -262,6 +282,9 @@ FT_Load_Glyph #Topic GPU_Context #Substitute GPU context +#Subtopic Resource_Cache_Limits +#Alias Resource_Cache_Limits +## #Class GrContext #Method void flush() ## @@ -279,95 +302,84 @@ FT_Load_Glyph ## ## -#Topic Image - #Subtopic Alpha_Type - #Alias Alpha_Type - #Enum SkAlphaType - #Const kUnknown_SkAlphaType 0 - ## - #Const kOpaque_SkAlphaType 1 - ## - #Const kPremul_SkAlphaType 2 - ## - #Const kUnpremul_SkAlphaType 3 - ## +#Topic Image_Alpha_Type +#Alias Alpha_Type +#Alias Alpha_Types + #Enum SkAlphaType + #Const kUnknown_SkAlphaType 0 ## - #Subtopic ## - #Subtopic Color_Type - #Alias Color_Type - #Alias Color_Types - #Enum SkColorType - #Const kUnknown_SkColorType 0 - ## - #Const kAlpha_8_SkColorType 1 - ## - #Const kRGB_565_SkColorType 2 - ## - #Const kARGB_4444_SkColorType 3 - ## - #Const kRGBA_8888_SkColorType 4 - ## - #Const kBGRA_8888_SkColorType 5 - ## - #Const kIndex_8_SkColorType 6 - ## - #Const kGray_8_SkColorType 7 - ## - #Const kRGBA_F16_SkColorType 8 - ## - #ToDo this is a lie; need to not require values for consts ## - #Const kN32_SkColorType 4 - ## - #Enum ## - #Subtopic ## - #Subtopic Info - #Struct SkImageInfo - #Method SkImageInfo() - ## - #Method static SkImageInfo MakeN32Premul(int width, int height, sk_sp<SkColorSpace> cs = nullptr) - ## - #Method SkImageInfo makeColorSpace(sk_sp<SkColorSpace> cs) const - ## - #Method size_t minRowBytes() const - ## - #Method bool isOpaque() const - ## - #Method int bytesPerPixel() const - ## - #Method int height() const - ## - #Method int width() const - ## - #Method SkColorType colorType() const - ## - #Method SkAlphaType alphaType() const - ## - #Method SkColorSpace* colorSpace() const - ## - #Method bool isOpaque() const - ## - #Method size_t minRowBytes() const - ## - #Method size_t computeByteSize(size_t rowBytes) const - ## - #Method void validate() const - ## - ## - #Subtopic ## - #Class SkImage - #Method sk_sp<SkShader> makeShader(SkShader::TileMode, SkShader::TileMode, - const SkMatrix* localMatrix = nullptr) const + #Const kOpaque_SkAlphaType 1 ## - #Method static sk_sp<SkImage> MakeRasterCopy(const SkPixmap&) + #Const kPremul_SkAlphaType 2 ## - #Method bool readPixels(const SkPixmap& dst, int srcX, int srcY, - CachingHint = kAllow_CachingHint) const + #Const kUnpremul_SkAlphaType 3 ## - #Method bool scalePixels(const SkPixmap& dst, SkFilterQuality, CachingHint = kAllow_CachingHint) const + ## +#Topic ## +#Topic Image_Color_Type +#Subtopic Native_Color_Type +#Alias Native_Color_Type +#Substitute native SkColorType +## +#Alias Color_Type +#Alias Color_Types + #Enum SkColorType + #Const kUnknown_SkColorType 0 ## - #Method bool peekPixels(SkPixmap* pixmap) const + #Const kAlpha_8_SkColorType 1 ## - ## + #Const kRGB_565_SkColorType 2 + ## + #Const kARGB_4444_SkColorType 3 + ## + #Const kRGBA_8888_SkColorType 4 + ## + #Const kBGRA_8888_SkColorType 5 + ## + #Const kIndex_8_SkColorType 6 + ## + #Const kGray_8_SkColorType 7 + ## + #Const kRGBA_F16_SkColorType 8 + ## + #ToDo this is a lie; need to not require values for consts ## + #Const kN32_SkColorType 4 + ## + #Enum ## +#Topic ## +#Topic Image_Info + #Struct SkImageInfo + #Method SkImageInfo() + ## + #Method static SkImageInfo MakeN32Premul(int width, int height, sk_sp<SkColorSpace> cs = nullptr) + ## + #Method SkImageInfo makeColorSpace(sk_sp<SkColorSpace> cs) const + ## + #Method size_t minRowBytes() const + ## + #Method bool isOpaque() const + ## + #Method int bytesPerPixel() const + ## + #Method int height() const + ## + #Method int width() const + ## + #Method SkColorType colorType() const + ## + #Method SkAlphaType alphaType() const + ## + #Method SkColorSpace* colorSpace() const + ## + #Method bool isOpaque() const + ## + #Method size_t minRowBytes() const + ## + #Method size_t computeByteSize(size_t rowBytes) const + ## + #Method void validate() const + ## + ## #Topic ## #Topic Image_Filter @@ -462,17 +474,18 @@ FT_Load_Glyph ## #Topic Mip_Map +#Alias Mip_Maps ## #Topic Nine_Patch ## #Topic Number_Types - #Typedef SkGlyphID + #Typedef uint16_t SkGlyphID #Typedef ## #Topic Scalar #Alias Scalar - #Typedef SkScalar + #Typedef float SkScalar #Typedef ## ## #Const SK_MinS32FitsInFloat @@ -502,9 +515,9 @@ FT_Load_Glyph #Const SK_MaxS32 to be written ## - #Typedef SkUnichar + #Typedef int32_t SkUnichar #Typedef ## - #Typedef U8CPU + #Typedef unsigned U8CPU #Typedef ## #Topic ## @@ -583,19 +596,17 @@ FT_Load_Glyph ## ## +#Topic Pixel_Serializer +#Class SkPixelSerializer +## +## + #Enum SkPixelGeometry ## -#Topic Point -#Alias Points - #Struct SkPoint - #Method bool equalsWithinTolerance(const SkPoint& p) const - ## - #Struct ## - #Subtopic Array - #Substitute SkPoint arrays - #Subtopic ## -#Topic ## +# Topic Point_Array +# Substitute SkPoint arrays +# Topic ## #Topic Point3 #Struct SkPoint3 @@ -648,6 +659,11 @@ FT_Load_Glyph ## #Topic ## +#Topic Render_Target +#Class GrRenderTarget +## +## + #Topic Right_Side_Bearing ## @@ -701,25 +717,12 @@ FT_Load_Glyph #Topic Supersampling ## -#Topic Surface -#Class SkSurface - #Method static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo&, void* pixels, size_t rowBytes, - const SkSurfaceProps* = nullptr) - ## - #Method bool readPixels(const SkPixmap& dst, int srcX, int srcY); - ## - #Method SkCanvas* getCanvas() - ## - #Method void flush() - ## - #Method void prepareForExternalIO() - ## - #Method sk_sp<SkSurface> makeSurface(const SkImageInfo&) - ## - #Method bool peekPixels(SkPixmap*) - ## +#Topic Surface_Characterization +#Class SkSurfaceCharacterization +## ## -#Subtopic Properties + +#Topic Surface_Properties #Class SkSurfaceProps #Topic Legacy_Font_Host #Enum InitType @@ -729,7 +732,6 @@ FT_Load_Glyph #Topic ## ## ## -## #Topic SVG #Subtopic Canvas @@ -746,21 +748,48 @@ FT_Load_Glyph #Class ## #Topic ## +#Topic Texture +#Class GrBackendTexture +## +## + #Topic Typeface #Class SkTypeface #Class ## #Topic ## +#Topic Types + #Typedef intptr_t GrBackendObject + #Typedef ## + + #Enum GrSurfaceOrigin + #Const kBottomLeft_GrSurfaceOrigin 0 + ## + #Const kTopLeft_GrSurfaceOrigin 1 + ## + #Enum ## + + #Subtopic Budgeted + #EnumClass SkBudgeted + #Const kNo 0 + ## + #Const kYes 1 + ## + #EnumClass ## + ## + + #EnumClass GrSemaphoresSubmitted + #Const kNo 0 + ## + #Const kYes 1 + ## + #EnumClass ## +#Topic ## + #Topic Unpremultiply #Alias Unpremultiplied ## -#Topic Vector -#Alias Vectors -#Struct SkVector -## -## - #Topic Vertices #Subtopic Colors ## |