From 06c20f356ddfcf95385c5d5ca9bf4428a7a16b81 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Tue, 20 Mar 2018 15:53:27 -0400 Subject: more SkImageInfo docs fix a couple of fiddles with changed output rewrite some SkSurface image makers move towards replacing SkImageInfo.h R=caryclark@google.com Docs-Preview: https://skia.org/?cl=115163 Bug: skia:6898 Change-Id: Id9895b051cd457336c30250a69cf95359d1d34d7 Reviewed-on: https://skia-review.googlesource.com/115163 Commit-Queue: Cary Clark Reviewed-by: Cary Clark --- docs/SkImageInfo_Reference.bmh | 296 +++++++++++++++++++++++++++-------------- 1 file changed, 198 insertions(+), 98 deletions(-) (limited to 'docs/SkImageInfo_Reference.bmh') diff --git a/docs/SkImageInfo_Reference.bmh b/docs/SkImageInfo_Reference.bmh index caa54b8731..516de4e35f 100644 --- a/docs/SkImageInfo_Reference.bmh +++ b/docs/SkImageInfo_Reference.bmh @@ -192,6 +192,17 @@ in the same order. #Subtopic Unpremul ## +#Method static inline bool SkAlphaTypeIsOpaque(SkAlphaType at) +#In Property +#Line # returns if Alpha_Type equals kOpaque_SkAlphaType ## + +#Param at one of: #list_of_alpha_types# +## +#Return true if at equals kOpaque_SkAlphaType ## +#NoExample +## +## + #Subtopic Alpha_Type ## # ------------------------------------------------------------------------------ @@ -216,6 +227,7 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType #Line # encoding for pixel color ## #Code +###$ enum SkColorType { kUnknown_SkColorType, kAlpha_8_SkColorType, @@ -228,10 +240,18 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType kRGB_101010x_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType, + kLastEnum_SkColorType = kRGBA_F16_SkColorType, + + #if SK_PMCOLOR_BYTE_ORDER(B,G,R,A) kN32_SkColorType = kBGRA_8888_SkColorType, + #elif SK_PMCOLOR_BYTE_ORDER(R,G,B,A) kN32_SkColorType = kRGBA_8888_SkColorType, + #else + #error "SK_*32_SHIFT values must correspond to BGRA or RGBA byte order" + #endif }; +$$$# ## Describes how pixel bits encode color. A pixel may be an alpha mask, a @@ -870,7 +890,7 @@ and return true if alphaType is not kUnknown_SkAlphaType. #Subtopic YUV_ColorSpace #Alias YUV_ColorSpace #Enum SkYUVColorSpace -#Line # incomplete ## +#Line # color range of YUV pixels ## #Code enum SkYUVColorSpace { @@ -881,25 +901,37 @@ and return true if alphaType is not kUnknown_SkAlphaType. }; ## -Describes the color space a YUV pixel. +Describes color range of YUV pixels. The color mapping from YUV to RGB varies +depending on the source. YUV pixels may be generated by JPEG images, standard +video streams, or high definition video streams. Each has its own mapping from +YUV and RGB. + +JPEG YUV values encode the full range of 0 to 255 for all three components. +Video YUV values range from 16 to 235 for all three components. Details of +encoding and conversion to RGB are described in +#A YCbCr color space # https://en.wikipedia.org/wiki/YCbCr ## +. #Const kJPEG_SkYUVColorSpace 0 -Standard JPEG color space. +Describes standard JPEG color space; +#A CCIR 601 # https://en.wikipedia.org/wiki/Rec._601 ## +with full range of 0 to 255 for components. ## #Const kRec601_SkYUVColorSpace 1 -SDTV standard Rec. 601 color space. Uses "studio swing" [16, 235] color -range. See http://en.wikipedia.org/wiki/Rec._601 for details. +Describes standard used by SDTV; +#A CCIR 601 # https://en.wikipedia.org/wiki/Rec._601 ## +with studio range of 16 to 235 range for components. ## #Const kRec709_SkYUVColorSpace 2 -HDTV standard Rec. 709 color space. Uses "studio swing" [16, 235] color -range. See http://en.wikipedia.org/wiki/Rec._709 for details. +Describes standard used by HDTV; +#A Rec. 709 # http://en.wikipedia.org/wiki/Rec._709 ## +with studio range of 16 to 235 range for components. ## -#Example -// incomplete +#NoExample ## -#SeeAlso incomplete +#SeeAlso SkImage::MakeFromYUVTexturesCopy SkImage::MakeFromNV12TexturesCopy #Enum SkYUVColorSpace ## #Subtopic YUV_ColorSpace ## @@ -934,7 +966,7 @@ and green; and Color_Space, the range and linearity of colors. #In Constructor #Line # creates with zero dimensions, kUnknown_SkColorType, kUnknown_SkAlphaType ## -Creates an empty Image_Info with kUnknown_SkColorType, kUnknown_SkAlphaType, +Creates an empty Image_Info with kUnknown_SkColorType, kUnknown_SkAlphaType, a width and height of zero, and no Color_Space. #Return empty Image_Info ## @@ -1122,6 +1154,7 @@ combination is supported. #Return created Image_Info ## #Example +#Height 128 SkBitmap bitmap; bitmap.allocPixels(SkImageInfo::MakeN32Premul(18, 18)); SkCanvas offscreen(bitmap); @@ -1157,6 +1190,7 @@ combination is supported. #Return created Image_Info ## #Example +#Height 128 SkBitmap bitmap; bitmap.allocPixels(SkImageInfo::MakeN32Premul({18, 18})); SkCanvas offscreen(bitmap); @@ -1855,7 +1889,7 @@ color: kRGBA_F16_SkColorType shiftPerPixel: 3 ## ## -#SeeAlso incomplete +#SeeAlso bytesPerPixel minRowBytes SkBitmap::shiftPerPixel SkPixmap::shiftPerPixel #Method ## @@ -1953,6 +1987,7 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect. #Return offset within pixel array ## #Example +#Height 128 uint8_t pixels[][12] = { { 0x00, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0x00}, { 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00}, { 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00}, @@ -1975,7 +2010,7 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect. canvas->drawBitmapRect(bitmap, SkRect::MakeWH(8, 8), SkRect::MakeWH(128, 128), &paint); ## -#SeeAlso incomplete +#SeeAlso height width minRowBytes computeByteSize #Method ## @@ -1985,64 +2020,68 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect. ## #Method bool operator==(const SkImageInfo& other)_const +#Line # compares Image_Info for equality ## -#Line # incomplete ## -#Param other incomplete ## - -#Return incomplete ## - -#Example -// incomplete -## - -#SeeAlso incomplete - -#Method ## - -# ------------------------------------------------------------------------------ - -#Method bool operator!=(const SkImageInfo& other)_const +Compares Image_Info with other, and returns true if width, height, Color_Type, +Alpha_Type, and Color_Space are equivalent. -#Line # incomplete ## -#Param other incomplete ## +#Param other Image_Info to compare ## -#Return incomplete ## +#Return true if Image_Info equals other ## #Example -// incomplete -## - -#SeeAlso incomplete + SkImageInfo info1 = SkImageInfo::Make(10, 20, kGray_8_SkColorType, kPremul_SkAlphaType); + SkImageInfo info2 = SkImageInfo::Make(20, 10, kAlpha_8_SkColorType, kUnpremul_SkAlphaType); + SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!'); + info2 = info2.makeWH(10, 20); + SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!'); + info2 = info2.makeColorType(kGray_8_SkColorType); + SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!'); + info2 = info2.makeAlphaType(kPremul_SkAlphaType); + SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!'); +#StdOut +info1 != info2 +info1 != info2 +info1 != info2 +info1 == info2 +## +## + +#SeeAlso operator!=(const SkImageInfo& other)_const SkColorSpace::Equals #Method ## # ------------------------------------------------------------------------------ -#Method void unflatten(SkReadBuffer& buffer) -#In Utility -#Line # incomplete ## -#Param buffer incomplete ## - -#Example -// incomplete -## - -#SeeAlso incomplete +#Method bool operator!=(const SkImageInfo& other)_const +#Line # compares Image_Info for inequality ## -#Method ## +Compares Image_Info with other, and returns true if width, height, Color_Type, +Alpha_Type, and Color_Space are equivalent. -# ------------------------------------------------------------------------------ +#Param other Image_Info to compare ## -#Method void flatten(SkWriteBuffer& buffer) const -#In Utility -#Line # incomplete ## -#Param buffer incomplete ## +#Return true if Image_Info is not equal to other ## #Example -// incomplete -## - -#SeeAlso incomplete + SkImageInfo info1 = SkImageInfo::Make(10, 20, kGray_8_SkColorType, kPremul_SkAlphaType); + SkImageInfo info2 = SkImageInfo::Make(20, 10, kAlpha_8_SkColorType, kUnpremul_SkAlphaType); + SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '='); + info2 = info2.makeWH(10, 20); + SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '='); + info2 = info2.makeColorType(kGray_8_SkColorType); + SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '='); + info2 = info2.makeAlphaType(kPremul_SkAlphaType); + SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '='); +#StdOut +info1 != info2 +info1 != info2 +info1 != info2 +info1 == info2 +## +## + +#SeeAlso operator==(const SkImageInfo& other)_const SkColorSpace::Equals #Method ## @@ -2050,25 +2089,33 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect. #Method size_t computeByteSize(size_t rowBytes) const #In Utility -#Line # incomplete ## -Returns the size (in bytes) of the image buffer that this info needs, given the specified -rowBytes. The rowBytes must be >= this->minRowBytes(). -if (height == 0) { -return 0; -} else { -return (height - 1) * rowBytes + width * bytes_per_pixel. +#Line # memory required by pixel buffer with given row bytes ## +Returns storage required by pixel array, given Image_Info dimensions, Color_Type, +and rowBytes. rowBytes is assumed to be at least as large as minRowBytes(). -If the calculation overflows this returns SK_MaxSizeT. +Returns zero if height is zero. +Returns SK_MaxSizeT if answer exceeds the range of size_t. -#Param rowBytes incomplete ## +#Param rowBytes size of pixel row or larger ## -#Return incomplete ## +#Return memory required by pixel buffer ## #Example -// incomplete -## - -#SeeAlso incomplete +#Height 130 + SkImageInfo info = SkImageInfo::MakeN32Premul(2, 2); + const size_t size = info.computeByteSize(100000); + SkAutoTMalloc storage(size); + SkPMColor* pixels = storage.get(); + SkBitmap bitmap; + bitmap.setInfo(info); + bitmap.setPixels(pixels); + bitmap.eraseColor(SK_ColorRED); + canvas->scale(50, 50); + canvas->rotate(8); + canvas->drawBitmap(bitmap, 2, 0); +## + +#SeeAlso computeMinByteSize validRowBytes #Method ## @@ -2076,17 +2123,31 @@ If the calculation overflows this returns SK_MaxSizeT. #Method size_t computeMinByteSize() const #In Utility -#Line # incomplete ## -Returns the minimum size (in bytes) of the image buffer that this info needs. -If the calculation overflows, or if the height is 0, this returns 0. +#Line # least memory required by pixel buffer ## +Returns storage required by pixel array, given Image_Info dimensions, and +Color_Type. Uses minRowBytes() to compute bytes for pixel row. -#Return incomplete ## +Returns zero if height is zero. +Returns SK_MaxSizeT if answer exceeds the range of size_t. -#Example -// incomplete -## +#Return least memory required by pixel buffer ## -#SeeAlso incomplete +#Example +#Height 130 + SkImageInfo info = SkImageInfo::MakeN32Premul(2, 2); + const size_t size = info.computeMinByteSize(); + SkAutoTMalloc storage(size); + SkPMColor* pixels = storage.get(); + SkBitmap bitmap; + bitmap.setInfo(info); + bitmap.setPixels(pixels); + bitmap.eraseColor(SK_ColorRED); + canvas->scale(50, 50); + canvas->rotate(8); + canvas->drawBitmap(bitmap, 2, 0); +## + +#SeeAlso computeByteSize validRowBytes #Method ## @@ -2094,18 +2155,31 @@ If the calculation overflows, or if the height is 0, this returns 0. #Method static bool ByteSizeOverflowed(size_t byteSize) #In Utility -#Line # incomplete ## -Returns true if the result of computeByteSize (or computeMinByteSize) overflowed +#Line # checks result of computeByteSize and computeMinByteSize ## +Returns true if byteSize equals SK_MaxSizeT. computeByteSize and +computeMinByteSize return SK_MaxSizeT if size_t can not hold buffer size. -#Param byteSize incomplete ## +#Param byteSize result of computeByteSize or computeMinByteSize ## -#Return incomplete ## +#Return true if computeByteSize or computeMinByteSize result exceeds size_t ## #Example -// incomplete -## - -#SeeAlso incomplete + SkImageInfo info = SkImageInfo::MakeN32Premul(2, 1000000000); + for (size_t rowBytes = 100000000; rowBytes < 10000000000000LL; rowBytes *= 10) { + const size_t size = info.computeByteSize(rowBytes); + SkDebugf("rowBytes:%llu size:%llu overflowed:%s\n", rowBytes, size, + SkImageInfo::ByteSizeOverflowed(size) ? "true" : "false"); + } +#StdOut +rowBytes:100000000 size:99999999900000008 overflowed:false +rowBytes:1000000000 size:999999999000000008 overflowed:false +rowBytes:10000000000 size:9999999990000000008 overflowed:false +rowBytes:100000000000 size:18446744073709551615 overflowed:true +rowBytes:1000000000000 size:18446744073709551615 overflowed:true +## +## + +#SeeAlso computeByteSize computeMinByteSize validRowBytes #Method ## @@ -2113,16 +2187,27 @@ Returns true if the result of computeByteSize (or computeMinByteSize) overflowed #Method bool validRowBytes(size_t rowBytes) const #In Utility -#Line # incomplete ## -#Param rowBytes incomplete ## +#Line # checks if row bytes is large enough to contain pixel row ## +Returns true if rowBytes is smaller than width times pixel size. -#Return incomplete ## +#Param rowBytes size of pixel row or larger ## + +#Return true if rowBytes is large enough to contain pixel row ## #Example -// incomplete + SkImageInfo info = SkImageInfo::MakeN32Premul(16, 8); + for (size_t rowBytes = 60; rowBytes < 72; rowBytes += sizeof(SkPMColor)) { + SkDebugf("validRowBytes(%llu): %s\n", rowBytes, info.validRowBytes(rowBytes) ? + "true" : "false"); + } +#StdOut +validRowBytes(60): false +validRowBytes(64): true +validRowBytes(68): true +## ## -#SeeAlso incomplete +#SeeAlso ByteSizeOverflowed computeByteSize computeMinByteSize #Method ## @@ -2130,12 +2215,25 @@ Returns true if the result of computeByteSize (or computeMinByteSize) overflowed #Method void reset() #In Constructor -#Line # incomplete ## +#Line # sets zero dimensions, kUnknown_SkColorType, kUnknown_SkAlphaType ## +Creates an empty Image_Info with kUnknown_SkColorType, kUnknown_SkAlphaType, +a width and height of zero, and no Color_Space. + #Example -// incomplete + SkImageInfo info = SkImageInfo::MakeN32Premul(16, 8); + SkImageInfo copy = info; + SkDebugf("info %c= copy\n", info == copy ? '=' : '!'); + copy.reset(); + SkDebugf("info %c= reset copy\n", info == copy ? '=' : '!'); + SkDebugf("SkImageInfo() %c= reset copy\n", SkImageInfo() == copy ? '=' : '!'); +#StdOut +info == copy +info != reset copy +SkImageInfo() == reset copy +## ## -#SeeAlso incomplete +#SeeAlso SkImageInfo() #Method ## @@ -2147,12 +2245,14 @@ Returns true if the result of computeByteSize (or computeMinByteSize) overflowed #Method void validate() const #In Utility -#Line # incomplete ## -#Example -// incomplete +#Line # asserts if Image_Info is invalid (debug only) ## +Asserts if internal values are illegal or inconsistent. Only available if +SK_DEBUG is defined at compile time. + +#NoExample ## -#SeeAlso incomplete +#SeeAlso validRowBytes SkBitmap::validate #Method ## -- cgit v1.2.3