From 154beea85961f73ed7f0da047b7ebd16d2a2d829 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Thu, 26 Oct 2017 07:58:48 -0400 Subject: Add docs for SkMatrix, SkRect, SkIRect, SkBitmap Also minor changes to earlier docs. Many small changes to improve indentation in generated includes. Added support for matrix math illustrations. Docs-Preview: https://skia.org/?cl=58500 Bug: skia:6898 Change-Id: I7da58ad55f82d7fd41d19288beb2cd71730fb01f Reviewed-on: https://skia-review.googlesource.com/58500 Commit-Queue: Cary Clark Reviewed-by: Cary Clark Reviewed-by: Cary Clark --- docs/SkBitmap_Reference.bmh | 239 ++++++++------------------------------------ 1 file changed, 41 insertions(+), 198 deletions(-) (limited to 'docs/SkBitmap_Reference.bmh') diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh index 27580233da..75cd57ed99 100644 --- a/docs/SkBitmap_Reference.bmh +++ b/docs/SkBitmap_Reference.bmh @@ -89,8 +89,7 @@ is useful to position one or more Bitmaps within a shared pixel array. # bytesPerPixel # Returns number of bytes in pixel based on Color_Type. ## # colorSpace # Returns Image_Info Color_Space. ## # colorType # Returns Image_Info Color_Type. ## -# computeSafeSize64 # Returns minimum size required for pixels in 64 bits. ## -# computeSize64 # Returns conservative size required for pixels. ## +# computeByteSize # Returns size required for pixels. ## # dimensions # Returns width and height. ## # drawsNothing # Returns true if no width, no height, or no Pixel_Ref. ## # empty() # Returns true if Image_Info has zero width or height. ## @@ -98,7 +97,7 @@ is useful to position one or more Bitmaps within a shared pixel array. # eraseARGB # Writes Color to pixels. ## # eraseArea # Deprecated ## # eraseColor # Writes Color to pixels. ## -# eraseRGB # Writes opaque Color to pixels. ## +# eraseRGB # Deprecated ## # extractAlpha # Creates Bitmap containing Alpha of pixels. ## # extractSubset # Creates Bitmap, sharing pixels if possible. ## # getAddr # Returns readable pixel address as void pointer. ## @@ -109,8 +108,6 @@ is useful to position one or more Bitmaps within a shared pixel array. # getColor # Returns one pixel as Unpremultiplied Color. ## # getGenerationID # Returns unique ID. ## # getPixels # Returns address of pixels. ## -# getSafeSize # Returns minimum size required for pixels in 32 bits. ## -# getSize # Returns conservative size required for pixels in 32 bits. ## # getSubset # Returns bounds offset by origin. ## # hasHardwareMipMap # Returns Mip_Map support present; Android only. ## # height # Returns pixel row count. ## @@ -144,6 +141,7 @@ is useful to position one or more Bitmaps within a shared pixel array. # tryAllocN32Pixels # Allocates compatible Color_ARGB pixels if possible. ## # tryAllocPixels # Allocates pixels from Image_Info if possible. ## # tryAllocPixelsFlags # Allocates pixels from Image_Info with options if possible. ## +# validate() # Asserts if Bitmap is invalid (debug only). ## # width() # Returns pixel column count. ## # writePixels # Copies and converts pixels. ## #Table ## @@ -480,6 +478,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: + #Formula rowBytes() / info().bytesPerPixel() ## @@ -1004,171 +1003,6 @@ width: 1000000 height: 1000000 computeByteSize: 4999999000000 # ------------------------------------------------------------------------------ -#Method size_t getSize() const - -Returns conservative memory required for pixel storage. -Includes unused memory on last row when rowBytesAsPixels exceeds width(). - -Does not check to see if result fits in 32 bits. Use getSize64() if the -result may exceed 32 bits. - -#Return height() times rowBytes() ## - -#Example -#Description -getSize results are not useful when width() and height() are large. -## -void draw(SkCanvas* canvas) { - SkBitmap bitmap; - for (int width : { 1, 1000, 1000000 } ) { - for (int height: { 1, 1000, 1000000 } ) { - SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - bitmap.setInfo(imageInfo, width * 5); - SkDebugf("width: %7d height: %7d getSize: %9zu\n", width, height, bitmap.getSize()); - } - } -} -#StdOut -width: 1 height: 1 getSize: 5 -width: 1 height: 1000 getSize: 5000 -width: 1 height: 1000000 getSize: 5000000 -width: 1000 height: 1 getSize: 5000 -width: 1000 height: 1000 getSize: 5000000 -width: 1000 height: 1000000 getSize: 705032704 -width: 1000000 height: 1 getSize: 5000000 -width: 1000000 height: 1000 getSize: 705032704 -width: 1000000 height: 1000000 getSize: 658067456 -## -## - -#SeeAlso getSafeSize computeSize64 rowBytes width() - -## - -# ------------------------------------------------------------------------------ - -#Method size_t getSafeSize() const - -Returns minimum memory required for pixel storage. -Does not include unused memory on last row when rowBytesAsPixels exceeds width(). - -Returns zero if size does not fit in 32 bits. Use computeSafeSize64 if the -result may exceed 32 bits. - -The pixel storage visible may be a subset of the Pixel_Ref. Accessing memory -beyond the result may generate an exception. - -#Return exact pixel storage size ## - -#Example -#Description -getSafeSize results are not useful when width() and height() are large. -## -void draw(SkCanvas* canvas) { - SkBitmap bitmap; - for (int width : { 1, 1000, 1000000 } ) { - for (int height: { 1, 1000, 1000000 } ) { - SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - bitmap.setInfo(imageInfo, width * 5); - SkDebugf("width: %7d height: %7d getSafeSize: %9zu\n", width, height, bitmap.getSafeSize()); - } - } -} -#StdOut -width: 1 height: 1 getSafeSize: 4 -width: 1 height: 1000 getSafeSize: 4999 -width: 1 height: 1000000 getSafeSize: 4999999 -width: 1000 height: 1 getSafeSize: 4000 -width: 1000 height: 1000 getSafeSize: 4999000 -width: 1000 height: 1000000 getSafeSize: 0 -width: 1000000 height: 1 getSafeSize: 4000000 -width: 1000000 height: 1000 getSafeSize: 0 -width: 1000000 height: 1000000 getSafeSize: 0 -## -## - -#SeeAlso getSize computeSafeSize64 rowBytes width() - -## - -# ------------------------------------------------------------------------------ - -#Method int64_t computeSize64() const - -Returns conservative memory required for pixel storage. -Includes unused memory on last row when rowBytesAsPixels exceeds width(). - -#Return conservative pixel storage size ## - -#Example -void draw(SkCanvas* canvas) { - SkBitmap bitmap; - for (int width : { 1, 1000, 1000000 } ) { - for (int height: { 1, 1000, 1000000 } ) { - SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - bitmap.setInfo(imageInfo, width * 5); - SkDebugf("width: %7d height: %7d computeSize64: %13lld\n", width, height, - bitmap.computeSize64()); - } - } -} -#StdOut -width: 1 height: 1 computeSize64: 5 -width: 1 height: 1000 computeSize64: 5000 -width: 1 height: 1000000 computeSize64: 5000000 -width: 1000 height: 1 computeSize64: 5000 -width: 1000 height: 1000 computeSize64: 5000000 -width: 1000 height: 1000000 computeSize64: 5000000000 -width: 1000000 height: 1 computeSize64: 5000000 -width: 1000000 height: 1000 computeSize64: 5000000000 -width: 1000000 height: 1000000 computeSize64: 5000000000000 -## -## - -#SeeAlso getSize computeSafeSize64 rowBytes width() - -## - -# ------------------------------------------------------------------------------ - -#Method int64_t computeSafeSize64() const - -Returns minimum memory required for pixel storage. -Does not include unused memory on last row when rowBytesAsPixels exceeds width(). - -#Return exact pixel storage size ## - -#Example -void draw(SkCanvas* canvas) { - SkBitmap bitmap; - for (int width : { 1, 1000, 1000000 } ) { - for (int height: { 1, 1000, 1000000 } ) { - SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - bitmap.setInfo(imageInfo, width * 5); - SkDebugf("width: %7d height: %7d computeSafeSize64: %13lld\n", width, height, - bitmap.computeSafeSize64()); - } - } -} -#StdOut -width: 1 height: 1 computeSafeSize64: 4 -width: 1 height: 1000 computeSafeSize64: 4999 -width: 1 height: 1000000 computeSafeSize64: 4999999 -width: 1000 height: 1 computeSafeSize64: 4000 -width: 1000 height: 1000 computeSafeSize64: 4999000 -width: 1000 height: 1000000 computeSafeSize64: 4999999000 -width: 1000000 height: 1 computeSafeSize64: 4000000 -width: 1000000 height: 1000 computeSafeSize64: 4999000000 -width: 1000000 height: 1000000 computeSafeSize64: 4999999000000 -## -## - -#SeeAlso getSafeSize computeSize64 rowBytes width() - -## - -# ------------------------------------------------------------------------------ - #Method bool isImmutable() const Returns true if pixels can not change. @@ -1201,9 +1035,9 @@ copy is immutable #Method void setImmutable() -Once set, pixels can not change. Any other bitmap sharing the same Pixel_Ref -are also marked as immutable. Once Pixel_Ref is marked immutable, the setting -cannot be cleared. +Sets internal flag to mark Bitmap as immutable. Once set, pixels can not change. +Any other bitmap sharing the same Pixel_Ref are also marked as immutable. +Once Pixel_Ref is marked immutable, the setting cannot be cleared. Writing to immutable Bitmap pixels triggers an assert on debug builds. @@ -2547,7 +2381,7 @@ then Color_RGB is ignored. canvas->drawBitmap(bitmap, 0, 0); ## -#SeeAlso eraseARGB eraseRGB erase +#SeeAlso eraseARGB erase ## @@ -2576,7 +2410,7 @@ then r, g, and b are ignored. canvas->drawBitmap(bitmap, .5f, .5f); ## -#SeeAlso eraseColor eraseRGB erase +#SeeAlso eraseColor erase ## @@ -2584,22 +2418,13 @@ then r, g, and b are ignored. #Method void eraseRGB(U8CPU r, U8CPU g, U8CPU b) const -Replaces pixel values with Color built from r, g, and b with Color_Alpha set -to 255. All pixels contained by bounds() are affected. -If colorType is kAlpha_8_SkColorType, all pixels are set to 255. +Deprecated. Use eraseARGB or eraseColor. -#Param r amount of Color_RGB_Red, from no red (0) to full red (255) ## -#Param g amount of Color_RGB_Green, from no green (0) to full green (255) ## -#Param b amount of Color_RGB_Blue, from no blue (0) to full blue (255) ## +#Param r amount of red ## +#Param g amount of green ## +#Param b amount of blue ## -#Example -#Height 80 - SkBitmap bitmap; - bitmap.allocPixels(SkImageInfo::MakeN32(1, 1, kPremul_SkAlphaType)); - bitmap.eraseRGB(0xff, 0x7f, 0x3f); - canvas->scale(50, 50); - canvas->drawBitmap(bitmap, 0, 0); - canvas->drawBitmap(bitmap, .5f, .5f); +#NoExample ## #SeeAlso eraseColor eraseARGB erase @@ -2950,7 +2775,8 @@ match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns false if pixel conversion is not possible. srcX and srcY may be negative to copy only top or left of source. Returns -false if width() or height() is zero or negative. Returns false if +false if width() or height() is zero or negative. +Returns false if #Formula abs(srcX) >= this->width() ## @@ -3034,7 +2860,8 @@ match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns false if pixel conversion is not possible. srcX and srcY may be negative to copy only top or left of source. Returns -false if width() or height() is zero or negative. Returns false if +false if width() or height() is zero or negative. +Returns false if #Formula abs(srcX) >= this->width() ## @@ -3108,7 +2935,8 @@ match. If this->colorSpace is nullptr, dst Color_Space must match. Returns false if pixel conversion is not possible. srcX and srcY may be negative to copy only top or left of source. Returns -false if width() or height() is zero or negative. Returns false if +false if width() or height() is zero or negative. +Returns false if #Formula abs(srcX) >= this->width() ## @@ -3220,7 +3048,8 @@ match. If this->colorSpace is nullptr, src Color_Space must match. Returns false if pixel conversion is not possible. dstX and dstY may be negative to copy only top or left of source. Returns -false if width() or height() is zero or negative. Returns false if +false if width() or height() is zero or negative. +Returns false if #Formula abs(dstX) >= this->width() ## @@ -3541,11 +3370,11 @@ mask. #Method bool peekPixels(SkPixmap* pixmap) const -If the pixels are available from this bitmap return true, and fill out the -specified pixmap (if not null). If there are no pixels, return false and -ignore the pixmap parameter. -Note: if this returns true, the results (in the pixmap) are only valid until the bitmap -is changed in any way, in which case the results are invalid. +Copies Bitmap 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 Bitmap. #Param pixmap storage for pixel state if pixels are readable; otherwise, ignored ## @@ -3590,6 +3419,20 @@ is changed in any way, in which case the results are invalid. # ------------------------------------------------------------------------------ +#Method void validate() const; + +Asserts if internal values are illegal or inconsistent. Only available if +SK_DEBUG is defined at compile time. + +#NoExample +## + +#SeeAlso SkImageInfo::validate() + +## + +# ------------------------------------------------------------------------------ + #Method void toString(SkString* str) const; #DefinedBy SK_TO_STRING_NONVIRT() ## -- cgit v1.2.3