From bc5697d3b13b082ade1e8397952265dd604664d1 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Wed, 4 Oct 2017 14:31:33 -0400 Subject: starting next gaggle of docs starting next gaggle of docs Docs-Preview: https://skia.org/?cl=50264 Bug: skia:6898 Change-Id: I639795b55c0c96b2efccac13cb67592f055a75a2 Reviewed-on: https://skia-review.googlesource.com/50264 Commit-Queue: Cary Clark Reviewed-by: Cary Clark --- docs/SkPixmap_Reference.bmh | 146 +++++++++++++++++++++----------------------- 1 file changed, 71 insertions(+), 75 deletions(-) (limited to 'docs/SkPixmap_Reference.bmh') diff --git a/docs/SkPixmap_Reference.bmh b/docs/SkPixmap_Reference.bmh index 521d6dea15..09fb1a68fe 100644 --- a/docs/SkPixmap_Reference.bmh +++ b/docs/SkPixmap_Reference.bmh @@ -11,8 +11,8 @@ a direct drawing destination. Use Bitmap to draw pixels referenced by Pixmap; use Surface to draw into pixels referenced by Pixmap. -Pixmap does not try to manage the lifetime of the pixel memory. Use PixelRef -to manage pixel memory; PixelRef is safe across threads. +Pixmap does not try to manage the lifetime of the pixel memory. Use Pixel_Ref +to manage pixel memory; Pixel_Ref is safe across threads. #Topic Overview @@ -401,7 +401,8 @@ width() * info().bytesPerPixel() ## . -It is up to the Pixmap creator to ensure that row bytes is a useful value. +Returns zero if colorType is kUnknown_SkColorType. +It is up to the Bitmap creator to ensure that row bytes is a useful value. #Return byte length of pixel row ## @@ -461,7 +462,7 @@ inset address: 0x7f2a440fb210 Returns pixel count in each pixel row. Should be equal or less than: #Formula -rowBytes() / info.bytesPerPixel() +rowBytes() / info().bytesPerPixel() ## . @@ -476,7 +477,7 @@ pixmap width: 16 info width: 16 ## ## -#SeeAlso height() +#SeeAlso height() SkImageInfo::width() ## @@ -489,15 +490,14 @@ Returns pixel row count. #Return pixel height in Image_Info ## #Example - SkImageInfo info = SkImageInfo::MakeA8(16, 32); - SkPixmap pixmap(info, nullptr, 64); - SkDebugf("pixmap height: %d info height: %d\n", pixmap.height(), info.height()); + SkPixmap pixmap(SkImageInfo::MakeA8(16, 32), nullptr, 64); + SkDebugf("pixmap height: %d info height: %d\n", pixmap.height(), pixmap.info().height()); #StdOut pixmap height: 32 info height: 32 ## ## -#SeeAlso width() +#SeeAlso width() ImageInfo::height() ## @@ -521,7 +521,7 @@ color type: kAlpha_SkColorType ## ## -#SeeAlso alphaType() +#SeeAlso alphaType() SkImageInfo::colorType ## @@ -543,7 +543,7 @@ alpha type: kPremul_SkAlphaType ## ## -#SeeAlso colorType() +#SeeAlso colorType() SkImageInfo::alphaType ## @@ -551,9 +551,11 @@ alpha type: kPremul_SkAlphaType #Method SkColorSpace* colorSpace() const -Returns Color_Space associated with Image_Info. +Returns Color_Space associated with Image_Info. The +reference count of Color_Space is unchanged. The returned Color_Space is +immutable. -#Return Color_Space in Image_Info ## +#Return Color_Space, the range of colors, in Image_Info ## #Example #Description @@ -572,7 +574,7 @@ gammaCloseToSRGB: false gammaIsLinear: true isSRGB: false ## ## -#SeeAlso Color_Space +#SeeAlso Color_Space SkImageInfo::colorSpace ## @@ -581,7 +583,8 @@ gammaCloseToSRGB: false gammaIsLinear: true isSRGB: false #Method bool isOpaque() const Returns true if Alpha_Type is kOpaque_SkAlphaType. -Does not check if Color_Type allows Alpha, or Alpha in pixel values. +Does not check if Color_Type allows Alpha, or if any pixel value has +transparency. #Return true if Image_Info has opaque Alpha_Type ## @@ -717,31 +720,15 @@ color: kRGBA_F16_SkColorType bytesPerPixel: 8 shiftPerPixel: 3 #Method uint64_t getSize64() const +#Deprecated +## + Returns conservative memory required for pixel storage. Includes unused memory on last row when rowBytesAsPixels exceeds width(). #Return conservative pixel storage size ## -#Example - SkPixmap pixmap; - for (int width : { 1, 1000, 1000000 } ) { - for (int height: { 1, 1000, 1000000 } ) { - SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - pixmap.reset(imageInfo , nullptr, width * 5); - SkDebugf("width: %7d height: %7d getSize64: %13lld\n", width, height, pixmap.getSize64()); - } - } -#StdOut -width: 1 height: 1 getSize64: 5 -width: 1 height: 1000 getSize64: 5000 -width: 1 height: 1000000 getSize64: 5000000 -width: 1000 height: 1 getSize64: 5000 -width: 1000 height: 1000 getSize64: 5000000 -width: 1000 height: 1000000 getSize64: 5000000000 -width: 1000000 height: 1 getSize64: 5000000 -width: 1000000 height: 1000 getSize64: 5000000000 -width: 1000000 height: 1000000 getSize64: 5000000000000 -## +#NoExample ## #SeeAlso getSafeSize64 getSafeSize height() rowBytes width() SkImageInfo::bytesPerPixel @@ -752,32 +739,15 @@ width: 1000000 height: 1000000 getSize64: 5000000000000 #Method uint64_t getSafeSize64() const +#Deprecated +## + 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 - SkPixmap pixmap; - for (int width : { 1, 1000, 1000000 } ) { - for (int height: { 1, 1000, 1000000 } ) { - SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - pixmap.reset(imageInfo , nullptr, width * 5); - SkDebugf("width: %7d height: %7d getSafeSize64: %13lld\n", width, height, - pixmap.getSafeSize64()); - } - } -#StdOut -width: 1 height: 1 getSafeSize64: 4 -width: 1 height: 1000 getSafeSize64: 4999 -width: 1 height: 1000000 getSafeSize64: 4999999 -width: 1000 height: 1 getSafeSize64: 4000 -width: 1000 height: 1000 getSafeSize64: 4999000 -width: 1000 height: 1000000 getSafeSize64: 4999999000 -width: 1000000 height: 1 getSafeSize64: 4000000 -width: 1000000 height: 1000 getSafeSize64: 4999000000 -width: 1000000 height: 1000000 getSafeSize64: 4999999000000 -## +#NoExample ## #SeeAlso getSize64 getSafeSize height() rowBytes width() SkImageInfo::bytesPerPixel @@ -788,6 +758,9 @@ width: 1000000 height: 1000000 getSafeSize64: 4999999000000 #Method size_t getSafeSize() const +#Deprecated +## + Returns minimum memory required for pixel storage. Does not include unused memory on last row when rowBytesAsPixels exceeds width(). Returns zero if value is does not fit in a signed 32-bit integer. @@ -795,31 +768,50 @@ The largest value than can be returned is 2,147,483,647. #Return exact pixel storage size if size fits in signed 32 bits ## +#NoExample +## + +#SeeAlso getSize64 getSafeSize64 height() rowBytes width() SkImageInfo::bytesPerPixel sk_64_isS32 + +## + + +# ------------------------------------------------------------------------------ + +#Method size_t computeByteSize() const + +Returns minimum memory required for pixel storage. +Does not include unused memory on last row when rowBytesAsPixels exceeds width(). +Returns zero if result does not fit in size_t. +Returns zero if height() or width() is 0. +Returns height() times rowBytes if colorType is kUnknown_SkColorType. + +#Return size in bytes of image buffer ## + #Example -void draw(SkCanvas* canvas) { SkPixmap pixmap; for (int width : { 1, 1000, 1000000 } ) { for (int height: { 1, 1000, 1000000 } ) { SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType); - pixmap.reset(imageInfo , nullptr, width * 5); - SkDebugf("width: %7d height: %7d getSafeSize: %7d\n", width, height, pixmap.getSafeSize()); + pixmap.reset(imageInfo, nullptr, width * 5); + SkDebugf("width: %7d height: %7d computeByteSize: %13lld\n", width, height, + pixmap.computeByteSize()); } } -} #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 +width: 1 height: 1 computeByteSize: 4 +width: 1 height: 1000 computeByteSize: 4999 +width: 1 height: 1000000 computeByteSize: 4999999 +width: 1000 height: 1 computeByteSize: 4000 +width: 1000 height: 1000 computeByteSize: 4999000 +width: 1000 height: 1000000 computeByteSize: 4999999000 +width: 1000000 height: 1 computeByteSize: 4000000 +width: 1000000 height: 1000 computeByteSize: 4999000000 +width: 1000000 height: 1000000 computeByteSize: 4999999000000 ## ## -#SeeAlso getSize64 getSafeSize64 height() rowBytes width() SkImageInfo::bytesPerPixel sk_64_isS32 +#SeeAlso SkImageInfo::computeByteSize ## @@ -845,7 +837,7 @@ greater. Returns false for kUnknown_SkColorType. -#Return true all pixels have opaque values or Color_Type is opaque ## +#Return true if all pixels have opaque values or Color_Type is opaque ## #Example std::vector pixels; @@ -943,10 +935,13 @@ Unpremultiplied: #Method const void* addr(int x, int y) const -Returns readable pixel address at (x, y). +Returns readable pixel address at (x, y). Returns nullptr if Pixel_Ref is nullptr. Input is not validated: out of bounds values of x or y trigger an assert() if -built with SK_DEBUG defined. Returns zero if Color_Type is kUnknown_SkColorType. +built with SK_DEBUG defined. Returns nullptr if Color_Type is kUnknown_SkColorType. + +Performs a lookup of pixel size; for better performance, call +one of: addr8, addr16, addr32, addr64, or addrF16. #Param x column index, zero or greater, and less than width() ## #Param y row index, zero or greater, and less than height() ## @@ -966,7 +961,7 @@ pixmap.addr(1, 2) == &storage[1 + 2 * w] ## ## -#SeeAlso addr8 addr16 addr32 addr64 addrF16 getColor writable_addr +#SeeAlso addr8 addr16 addr32 addr64 addrF16 getColor writable_addr SkBitmap::getAddr ## @@ -1611,7 +1606,7 @@ abs(srcY) >= this->height() If behavior is SkTransferFunctionBehavior::kRespect: converts source pixels to a linear space before converting to dstInfo. If behavior is SkTransferFunctionBehavior::kIgnore: source -pixels are treated as if they are linear, regardless of their encoding. +pixels are treated as if they are linear, regardless of how they are encoded. #Param dstInfo destination width, height, Color_Type, Alpha_Type, Color_Space ## #Param dstPixels destination pixel storage ## @@ -1625,6 +1620,7 @@ pixels are treated as if they are linear, regardless of their encoding. #Return true if pixels are copied to dstPixels ## #Example +#ToDo example doesn't do anything interesting since info colorSpace is nullptr ## #Image 3 void draw(SkCanvas* canvas) { SkImageInfo info = SkImageInfo::MakeN32Premul(image->width(), image->height(), -- cgit v1.2.3