From 681287eb67f13e12fbcca96e956dea77c2661583 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Fri, 16 Mar 2018 11:34:15 -0400 Subject: more imageinfo text and warnings and cleanup more imageinfo text rewrote many examples to fix newly exposed compiler warnings marked a couple of YUV method bodies as deprecated also cleaned up line endings to use the linux style R=bsalomon@google.com TBR=caryclark@google.com Docs-Preview: https://skia.org/?cl=112302 Bug: skia:6898 Change-Id: I89626a27353aa84526f9b9475d927bd0e9d8f0d5 Reviewed-on: https://skia-review.googlesource.com/112302 Reviewed-by: Brian Salomon Commit-Queue: Cary Clark --- docs/SkImageInfo_Reference.bmh | 738 +++++++++++++++++++++++++++++++++++------ 1 file changed, 628 insertions(+), 110 deletions(-) (limited to 'docs/SkImageInfo_Reference.bmh') diff --git a/docs/SkImageInfo_Reference.bmh b/docs/SkImageInfo_Reference.bmh index e2dbc4ae1a..caa54b8731 100644 --- a/docs/SkImageInfo_Reference.bmh +++ b/docs/SkImageInfo_Reference.bmh @@ -27,6 +27,11 @@ but Image and Surface may not contain Image_Info. #Alias Alpha_Type #Alias Alpha_Types +#PhraseDef list_of_alpha_types +kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType, +kUnpremul_SkAlphaType +## + #Enum SkAlphaType #Line # encoding for pixel transparency ## @@ -162,6 +167,7 @@ Some drawing destinations may not support Unpremul. #Bug 7079 #Example +#Height 64 #Description SkColorSetARGB parameter a is set to 150, less than its maximum value, and is interpreted as Color_Alpha of about 0.6. color is not premultiplied; @@ -449,7 +455,7 @@ the platform at compile time. #Subtopic RGB_888x RGB_888x is a 32-bit word pixel encoding that contains eight bits of red, -eight bits of green, eight bits of blue, and eight unused bits. RGB_888x is fully +eight bits of green, eight bits of blue, and eight unused bits. RGB_888x is fully opaque as if its Color_Alpha was set to one, and should always be paired with kOpaque_SkAlphaType. @@ -587,6 +593,11 @@ less than 3, the drawn result is undefined. #Subtopic RGB_101010x +RGB_101010x is a 32-bit word pixel encoding that contains ten bits of red, +ten bits of green, ten bits of blue, and two unused bits. RGB_101010x is fully +opaque as if its Color_Alpha was set to one, and should always be paired with +kOpaque_SkAlphaType. + #Illustration #Example @@ -619,6 +630,11 @@ less than 3, the drawn result is undefined. #Subtopic Gray_8 +Gray_8 is an 8-bit byte pixel encoding that represents equal values for red, +blue, and green, reprsenting colors from black to white. Gray_8 is fully +opaque as if its Color_Alpha was set to one, and should always be paired with +kOpaque_SkAlphaType. + #Example #Height 64 canvas->scale(16, 16); @@ -638,8 +654,28 @@ less than 3, the drawn result is undefined. #Subtopic RGBA_F16 +RGBA_F16 is a 64-bit word pixel encoding that contains sixteen bits of blue, +sixteen bits of green, sixteen bits of red, and sixteen bits of alpha. + +Each component encodes a floating point value using +#A Half floats # https://www.khronos.org/opengl/wiki/Small_Float_Formats ## +. Meaningful colors are represented by the range 0.0 to 1.0, although smaller +and larger values may be useful when used in combination with Transfer_Mode. + #Illustration +If paired with kPremul_SkAlphaType: blue, green, and red components are +premultiplied by the alpha value. If blue, green, or red is greater than alpha, +the drawn result is undefined. + +If paired with kUnpremul_SkAlphaType: blue, green, red, and alpha components +may have any value. There may be a performance penalty with unpremultipled +pixels. + +If paired with kOpaque_SkAlphaType: all alpha component values are at the maximum; +blue, green, and red components are fully opaque. If any alpha component is +less than 255, the drawn result is undefined. + #ToDo FloatToHalf should be replaced with SkFloatToHalf if/when that's made public ## @@ -700,6 +736,136 @@ void draw(SkCanvas* canvas) { #Subtopic Color_Type ## +# ------------------------------------------------------------------------------ + +#Method int SkColorTypeBytesPerPixel(SkColorType ct) +#In Property +#Line # returns Color_Type byte size ## + +Returns the number of bytes required to store a pixel, including unused padding. +Returns zero if ct is kUnknown_SkColorType or invalid. + +#Param ct one of: #list_of_color_types# +## + +#Return bytes per pixel ## + +#Example +#Height 192 + const char* colors[] = { "Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", + "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16" }; + SkPaint paint; + paint.setTypeface(SkTypeface::MakeFromName("monospace", SkFontStyle())); + paint.setAntiAlias(true); + paint.setTextSize(10); + int y = 15; + canvas->drawString(" colorType bytes", 10, y, paint); + for (SkColorType colorType : { #list_of_color_types# + } ) { + int result = SkColorTypeBytesPerPixel(colorType); + SkString string; + string.printf("%13s %4d", colors[(int) colorType], result); + canvas->drawString(string, 10, y += 14, paint); + } +## +#SeeAlso SkImageInfo::bytesPerPixel +## + +# ------------------------------------------------------------------------------ + +#Method bool SkColorTypeIsAlwaysOpaque(SkColorType ct) +#In Property +#Line # returns if Color_Type includes Color_Alpha ## + +Returns true if Color_Type always decodes Color_Alpha to 1.0, making the pixel +fully opaque. If true, Color_Type does not reserve bits to encode Color_Alpha. + +#Param ct one of: #list_of_color_types# +## + +#Return true if Color_Alpha is always set to 1.0 ## + +#Example +#Height 192 + const char* colors[] = { "Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", + "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16" }; + SkPaint paint; + paint.setTypeface(SkTypeface::MakeFromName("monospace", SkFontStyle())); + paint.setAntiAlias(true); + paint.setTextSize(10); + int y = 15; + canvas->drawString(" colorType bytes", 10, y, paint); + for (SkColorType colorType : { #list_of_color_types# + } ) { + bool result = SkColorTypeIsAlwaysOpaque(colorType); + SkString string; + string.printf("%13s %6s", colors[(int) colorType], result ? "true" : "false"); + canvas->drawString(string, 10, y += 14, paint); + } +## +#SeeAlso SkColorTypeValidateAlphaType +## + +# ------------------------------------------------------------------------------ + +#Method bool SkColorTypeValidateAlphaType(SkColorType colorType, SkAlphaType alphaType, + SkAlphaType* canonical = nullptr) +#In Property +#Line # returns if Alpha_Type is valid ## + +Returns true if canonical can be set to a valid Alpha_Type for colorType. If +there is more than one valid canonical Alpha_Type, set to alphaType, if valid. +If true is returned and canonical is not nullptr, store valid Alpha_Type. + +Returns false only if alphaType is kUnknown_SkAlphaType, color type is not +kUnknown_SkColorType, and Color_Type is not always opaque. If false is returned, +canonical is ignored. + +For kUnknown_SkColorType: set canonical to kUnknown_SkAlphaType and return true. +For kAlpha_8_SkColorType: set canonical to kPremul_SkAlphaType or +kOpaque_SkAlphaType and return true if alphaType is not kUnknown_SkAlphaType. +For kRGB_565_SkColorType, kRGB_888x_SkColorType, kRGB_101010x_SkColorType, and +kGray_8_SkColorType: set canonical to kOpaque_SkAlphaType and return true. +For kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kBGRA_8888_SkColorType, +kRGBA_1010102_SkColorType, and kRGBA_F16_SkColorType: set canonical to alphaType +and return true if alphaType is not kUnknown_SkAlphaType. + +#Param colorType one of: #list_of_color_types# +## +#Param alphaType one of: #list_of_alpha_types# +## +#Param canonical storage for Alpha_Type ## + +#Return true if valid Alpha_Type can be associated with colorType ## + +#Example +#Height 640 + const char* colors[] = { "Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", + "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16" }; + const char* alphas[] = {"Unknown ", "Opaque ", "Premul ", "Unpremul"}; + SkAlphaType alphaTypes[] = { #list_of_alpha_types# + }; + SkPaint paint; + paint.setTypeface(SkTypeface::MakeFromName("monospace", SkFontStyle())); + paint.setAntiAlias(true); + paint.setTextSize(10); + int y = 15; + canvas->drawString(" colorType alphaType canonical", 10, y, paint); + for (SkColorType colorType : { #list_of_color_types# + } ) { + for (SkAlphaType alphaType : alphaTypes) { + SkAlphaType canonicalAlphaType = kUnknown_SkAlphaType; + bool result = SkColorTypeValidateAlphaType(colorType, alphaType, &canonicalAlphaType); + SkString string; + string.printf("%13s %10s %10s", colors[(int) colorType], alphas[(int) alphaType], + result ? alphas[(int) canonicalAlphaType] : "------ "); + canvas->drawString(string, 10, y += 14, paint); + } + } +## +#SeeAlso SkColorTypeIsAlwaysOpaque +## + # ------------------------------------------------------------------------------ #Subtopic YUV_ColorSpace #Alias YUV_ColorSpace @@ -738,30 +904,6 @@ range. See http://en.wikipedia.org/wiki/Rec._709 for details. #Enum SkYUVColorSpace ## #Subtopic YUV_ColorSpace ## -# ------------------------------------------------------------------------------ -#EnumClass SkDestinationSurfaceColorMode -#Line # incomplete ## - -#Code - enum class SkDestinationSurfaceColorMode { - kLegacy, - kGammaAndColorSpaceAware, - }; -## - -#Const kLegacy 0 -## -#Const kGammaAndColorSpaceAware 1 -## - -#Example -// incomplete -## - -#SeeAlso incomplete - -#EnumClass SkDestinationSurfaceColorMode ## - # ------------------------------------------------------------------------------ #Struct SkImageInfo @@ -806,7 +948,7 @@ for the Canvas actual Image_Info. SkImageInfo imageInfo; size_t rowBytes; SkIPoint origin; - uint32_t* access = (uint32_t*) canvas->accessTopLayerPixels(&imageInfo, &rowBytes, &origin); + (void) canvas->accessTopLayerPixels(&imageInfo, &rowBytes, &origin); const char* alphaType[] = { "Unknown", "Opaque", "Premul", "Unpremul" }; SkString string; string.printf("k%s_SkAlphaType", alphaType[(int) imageInfo.alphaType()]); @@ -837,8 +979,7 @@ combination is supported. #Param height pixel row count; must be zero or greater ## #Param ct one of: #list_of_color_types# ## -#Param at one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType, - kUnpremul_SkAlphaType +#Param at one of: #list_of_alpha_types# ## #Param cs range of colors; may be nullptr ## @@ -881,8 +1022,7 @@ combination is supported. #Param width pixel column count; must be zero or greater ## #Param height pixel row count; must be zero or greater ## -#Param at one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType, - kUnpremul_SkAlphaType +#Param at one of: #list_of_alpha_types# ## #Param cs range of colors; may be nullptr ## @@ -918,8 +1058,7 @@ combination is supported. #Param width pixel column count; must be zero or greater ## #Param height pixel row count; must be zero or greater ## -#Param at one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType, - kUnpremul_SkAlphaType +#Param at one of: #list_of_alpha_types# ## #Return created Image_Info ## @@ -1049,7 +1188,25 @@ kPremul_SkAlphaType, with Color_Space set to nullptr. #Return created Image_Info ## #Example -// incomplete +#Height 64 + uint8_t pixels[][8] = { { 0x00, 0x00, 0x3f, 0x00, 0x00, 0x00, 0x00, 0x00}, + { 0x00, 0x7f, 0xff, 0x3f, 0x3f, 0x7f, 0x3f, 0x00}, + { 0x3f, 0xff, 0x7f, 0x00, 0x7f, 0xff, 0x7f, 0x00}, + { 0x00, 0x3f, 0x00, 0x00, 0x3f, 0x7f, 0x3f, 0x00}, + { 0x3f, 0x7f, 0x7f, 0x3f, 0x00, 0x00, 0x00, 0x00}, + { 0x7f, 0xff, 0xff, 0x7f, 0x00, 0x3f, 0x7f, 0x3f}, + { 0x7f, 0xff, 0xff, 0x7f, 0x00, 0x7f, 0xff, 0x7f}, + { 0x3f, 0x7f, 0x7f, 0x3f, 0x00, 0x3f, 0x7f, 0x3f} }; + SkBitmap bitmap; + bitmap.installPixels(SkImageInfo::MakeA8(8, 8), + (void*) pixels, sizeof(pixels[0])); + SkPaint paint; + canvas->scale(4, 4); + for (auto color : { SK_ColorRED, SK_ColorBLUE, 0xFF007F00} ) { + paint.setColor(color); + canvas->drawBitmap(bitmap, 0, 0, &paint); + canvas->translate(12, 0); + } ## #SeeAlso MakeN32 MakeS32 Make @@ -1177,16 +1334,22 @@ Returns pixel row count. #Method SkColorType colorType() const #In Property -#Line # incomplete ## +#Line # returns Color_Type ## Returns Color_Type, one of: #list_of_color_types#. #Return Color_Type ## #Example -// incomplete + const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", + "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"}; + SkImageInfo info = SkImageInfo::MakeA8(16, 32); + SkDebugf("color type: k" "%s" "_SkColorType\n", colors[info.colorType()]); +#StdOut +color type: kAlpha_8_SkColorType +## ## -#SeeAlso incomplete +#SeeAlso alphaType SkPixmap::colorType SkBitmap::colorType #Method ## @@ -1194,14 +1357,21 @@ Returns Color_Type, one of: #list_of_color_types#. #Method SkAlphaType alphaType() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # Returns Alpha_Type ## +Returns Alpha_Type, one of: #list_of_alpha_types#. + +#Return Alpha_Type ## #Example -// incomplete + const char* alphas[] = {"Unknown", "Opaque", "Premul", "Unpremul"}; + SkImageInfo info = SkImageInfo::MakeA8(16, 32); + SkDebugf("alpha type: k" "%s" "_SkAlphaType\n", alphas[info.alphaType()]); +#StdOut +alpha type: kPremul_SkAlphaType +## ## -#SeeAlso incomplete +#SeeAlso colorType SkPixmap::alphaType SkBitmap::alphaType #Method ## @@ -1209,14 +1379,30 @@ Returns Color_Type, one of: #list_of_color_types#. #Method SkColorSpace* colorSpace() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns Color_Space ## +Returns Color_Space, the range of colors. The reference count of +Color_Space is unchanged. The returned Color_Space is immutable. + +#Return Color_Space, or nullptr ## #Example -// incomplete +#Description +SkColorSpace::MakeSRGBLinear creates Color_Space with linear gamma +and an sRGB gamut. This Color_Space gamma is not close to sRGB gamma. +## + SkImageInfo info = SkImageInfo::MakeN32(16, 32, kPremul_SkAlphaType, + SkColorSpace::MakeSRGBLinear()); + SkColorSpace* colorSpace = info.colorSpace(); + SkDebugf("gammaCloseToSRGB: %s gammaIsLinear: %s isSRGB: %s\n", + colorSpace->gammaCloseToSRGB() ? "true" : "false", + colorSpace->gammaIsLinear() ? "true" : "false", + colorSpace->isSRGB() ? "true" : "false"); +#StdOut +gammaCloseToSRGB: false gammaIsLinear: true isSRGB: false +## ## -#SeeAlso incomplete +#SeeAlso Color_Space SkPixmap::colorSpace SkBitmap::colorSpace #Method ## @@ -1224,14 +1410,28 @@ Returns Color_Type, one of: #list_of_color_types#. #Method sk_sp refColorSpace() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns Color_Space ## +Returns smart pointer to Color_Space, the range of colors. The smart pointer +tracks the number of objects sharing this Color_Space reference so the memory +is released when the owners destruct. + +The returned Color_Space is immutable. + +#Return Color_Space wrapped in a smart pointer ## #Example -// incomplete + SkImageInfo info1 = SkImageInfo::MakeN32(16, 32, kPremul_SkAlphaType, + SkColorSpace::MakeSRGBLinear()); + SkImageInfo info2 = SkImageInfo::MakeN32(16, 32, kPremul_SkAlphaType, + info1.refColorSpace()); + SkColorSpace* colorSpace = info2.colorSpace(); + SkDebugf("gammaCloseToSRGB: %s gammaIsLinear: %s isSRGB: %s\n", + colorSpace->gammaCloseToSRGB() ? "true" : "false", + colorSpace->gammaIsLinear() ? "true" : "false", + colorSpace->isSRGB() ? "true" : "false"); ## -#SeeAlso incomplete +#SeeAlso Color_Space SkBitmap::refColorSpace #Method ## @@ -1239,14 +1439,30 @@ Returns Color_Type, one of: #list_of_color_types#. #Method bool isEmpty() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns if dimensions contain pixels ## + +Returns if Image_Info describes an empty area of pixels by checking if either +width or height is zero or smaller. + +#Return true if either dimension is zero or smaller ## #Example -// incomplete + for (int width : { 0, 2 } ) { + for (int height : { 0, 2 } ) { + SkImageInfo imageInfo= SkImageInfo::MakeA8(width, height); + SkDebugf("width: %d height: %d empty: %s\n", width, height, + imageInfo.isEmpty() ? "true" : "false"); + } + } +#StdOut +width: 0 height: 0 empty: true +width: 0 height: 2 empty: true +width: 2 height: 0 empty: true +width: 2 height: 2 empty: false +## ## -#SeeAlso incomplete +#SeeAlso dimensions bounds SkBitmap::empty SkPixmap::bounds #Method ## @@ -1254,14 +1470,41 @@ Returns Color_Type, one of: #list_of_color_types#. #Method bool isOpaque() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns if Alpha_Type is kOpaque_SkAlphaType ## + +Returns true if Alpha_Type is set to hint that all pixels are opaque; their +Color_Alpha value is implicitly or explicitly 1.0. If true, and all pixels are +not opaque, Skia may draw incorrectly. + +Does not check if Color_Type allows Alpha, or if any pixel value has +transparency. + +#Return true if Alpha_Type is kOpaque_SkAlphaType ## #Example -// incomplete + const int height = 2; + const int width = 2; + SkBitmap bitmap; + SkImageInfo imageInfo = SkImageInfo::Make(width, height, kN32_SkColorType, kPremul_SkAlphaType); + bitmap.setInfo(imageInfo); + for (int index = 0; index < 2; ++index) { + bitmap.allocPixels(); + bitmap.eraseColor(0x00000000); + SkDebugf("isOpaque: %s\n", imageInfo.isOpaque() ? "true" : "false"); + bitmap.eraseColor(0xFFFFFFFF); + SkDebugf("isOpaque: %s\n", imageInfo.isOpaque() ? "true" : "false"); + imageInfo = imageInfo.makeAlphaType(kOpaque_SkAlphaType); + bitmap.setInfo(imageInfo); + } +#StdOut +isOpaque: false +isOpaque: false +isOpaque: true +isOpaque: true +## ## -#SeeAlso incomplete +#SeeAlso Color_Alpha SkColorTypeValidateAlphaType SkBitmap::isOpaque SkImage::isOpaque SkPixmap::isOpaque #Method ## @@ -1269,14 +1512,26 @@ Returns Color_Type, one of: #list_of_color_types#. #Method SkISize dimensions() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns width() and height() ## + +Returns ISize { width(), height() }. + +#Return integral size of width() and height() ## #Example -// incomplete + const int height = 2; + const int width = 2; + SkImageInfo imageInfo = SkImageInfo::Make(width, height, kN32_SkColorType, kPremul_SkAlphaType); + SkISize dimensions = imageInfo.dimensions(); + SkIRect bounds = imageInfo.bounds(); + SkIRect dimensionsAsBounds = SkIRect::MakeSize(dimensions); + SkDebugf("dimensionsAsBounds %c= bounds\n", dimensionsAsBounds == bounds ? '=' : '!'); +#StdOut +dimensionsAsBounds == bounds +## ## -#SeeAlso incomplete +#SeeAlso width height bounds SkBitmap::dimensions #Method ## @@ -1284,14 +1539,25 @@ Returns Color_Type, one of: #list_of_color_types#. #Method SkIRect bounds() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns width() and height() as Rectangle ## +Returns IRect { 0, 0, width(), height() }. + +#Return integral rectangle from origin to width() and height() ## #Example -// incomplete +#Height 64 +#Image 4 + canvas->scale(.5f, .5f); + SkImageInfo imageInfo = source.info(); + SkIRect bounds = imageInfo.bounds(); + for (int x : { 0, bounds.width() } ) { + for (int y : { 0, bounds.height() } ) { + canvas->drawBitmap(source, x, y); + } + } ## -#SeeAlso incomplete +#SeeAlso width height dimensions #Method ## @@ -1299,14 +1565,48 @@ Returns Color_Type, one of: #list_of_color_types#. #Method bool gammaCloseToSRGB() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # Returns if Color_Space gamma is approximately the same as sRGB ## + +Returns true if associated Color_Space is not nullptr, and Color_Space gamma +is approximately the same as sRGB. +This includes the +###$ +$A sRGB transfer function $ https://en.wikipedia.org/wiki/SRGB#The_sRGB_transfer_function_(%22gamma%22) $$ +$$$# +as well as a gamma curve described by a 2.2 exponent. + +#Return true if Color_Space gamma is approximately the same as sRGB ## #Example -// incomplete +#Height 144 + const int width = 256; + const int height = 64; + auto drawLabel = [=](const char* what, bool closeToSRGB) -> void { + SkString string; + string.printf("%s gamma is %s" "close to sRGB", what, closeToSRGB ? "" : "not "); + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextAlign(SkPaint::kCenter_Align); + canvas->drawString(string, width / 2, 56, paint); + }; + SkColor gradColors[] = { 0xFFFF7F00, 0xFF00FF7F, 0xFF0000FF, 0xFF7F7FFF }; + SkPoint gradPoints[] = { { 0, 0 }, { width, 0 }, { width * 2, 0 }, { width * 3, 0 } }; + SkPaint gradPaint; + gradPaint.setShader(SkGradientShader::MakeLinear(gradPoints, gradColors, nullptr, + SK_ARRAY_COUNT(gradColors), SkShader::kClamp_TileMode)); + canvas->drawRect(SkRect::MakeWH(width, height), gradPaint); + drawLabel("canvas", canvas->imageInfo().gammaCloseToSRGB()); + SkBitmap bitmap; + SkImageInfo offscreenInfo = SkImageInfo::MakeS32(width, height, kPremul_SkAlphaType); + bitmap.allocPixels(offscreenInfo); + SkCanvas sRGBOffscreen(bitmap); + sRGBOffscreen.drawRect(SkRect::MakeWH(width, height), gradPaint); + canvas->translate(0, 80); + canvas->drawBitmap(bitmap, 0, 0); + drawLabel("offscreen", offscreenInfo.gammaCloseToSRGB()); ## -#SeeAlso incomplete +#SeeAlso SkColorSpace::gammaCloseToSRGB #Method ## @@ -1315,19 +1615,30 @@ Returns Color_Type, one of: #list_of_color_types#. #Method SkImageInfo makeWH(int newWidth, int newHeight) const #In Constructor #Line # creates Image_Info with changed dimensions ## -Creates Image_Info with the same Color_Type and Alpha_Type as this info, -but with the specified width and height. +Creates Image_Info with the same Color_Type, Color_Space, and Alpha_Type, +with dimensions set to width and height. -#Param newWidth incomplete ## -#Param newHeight incomplete ## +#Param newWidth pixel column count; must be zero or greater ## +#Param newHeight pixel row count; must be zero or greater ## -#Return incomplete ## +#Return created Image_Info ## #Example -// incomplete -## - -#SeeAlso incomplete +#Height 144 +#Image 3 + SkImageInfo canvasImageInfo = canvas->imageInfo(); + SkRect canvasBounds = SkRect::Make(canvasImageInfo.bounds()); + canvas->drawBitmapRect(source, source.bounds(), canvasBounds, nullptr); + SkImageInfo insetImageInfo = + canvasImageInfo.makeWH(canvasBounds.width() / 2, canvasBounds.height() / 2); + SkBitmap inset; + inset.allocPixels(insetImageInfo); + SkCanvas offscreen(inset); + offscreen.drawBitmapRect(source, source.bounds(), SkRect::Make(inset.bounds()), nullptr); + canvas->drawBitmap(inset, canvasBounds.width() / 4, canvasBounds.height() / 4); +## + +#SeeAlso Make makeAlphaType makeColorSpace makeColorType #Method ## @@ -1336,15 +1647,43 @@ but with the specified width and height. #Method SkImageInfo makeAlphaType(SkAlphaType newAlphaType) const #In Constructor #Line # creates Image_Info with changed Alpha_Type ## -#Param newAlphaType incomplete ## +Creates Image_Info with same Color_Type, Color_Space, width, and height, +with Alpha_Type set to newAlphaType. -#Return incomplete ## +Created Image_Info contains newAlphaType even if it is incompatible with +Color_Type, in which case Alpha_Type in Image_Info is ignored. + +#Param newAlphaType one of: #list_of_alpha_types# +## + +#Return created Image_Info ## #Example -// incomplete +#Image 3 + const int width = 256; + const int height = 128; + SkColor pixels[height][width]; + for (int y = 0; y < height; ++y) { + for (int x = 0; x < width; ++x) { + int red = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarSin((x * 4 + y) * 0.03f))); + int blue = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarCos((x * 3 + y) * 0.04f))); + int green = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarSin((x * 2 + y) * 0.05f))); + int alpha = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarCos((x * 1 + y) * 0.006f))); + pixels[y][x] = + SkColorSetARGB(alpha, red * alpha / 255, green * alpha / 255, blue * alpha / 255); + } + } + SkBitmap bitmap; + SkImageInfo info = SkImageInfo::Make(width, height, kBGRA_8888_SkColorType, kPremul_SkAlphaType); + bitmap.installPixels(info, (void*) pixels, sizeof(SkColor) * width); + canvas->drawBitmap(source, 0, 0); + canvas->drawBitmap(bitmap, 0, 0); + SkImageInfo unpremulInfo = info.makeAlphaType(kUnpremul_SkAlphaType); + bitmap.installPixels(unpremulInfo, (void*) pixels, sizeof(SkColor) * width); + canvas->drawBitmap(bitmap, 0, 128); ## -#SeeAlso incomplete +#SeeAlso Make MakeA8 makeColorType makeColorSpace #Method ## @@ -1353,15 +1692,39 @@ but with the specified width and height. #Method SkImageInfo makeColorType(SkColorType newColorType) const #In Constructor #Line # creates Image_Info with changed Color_Type ## -#Param newColorType incomplete ## +Creates Image_Info with same Alpha_Type, Color_Space, width, and height, +with Color_Type set to newColorType. -#Return incomplete ## +#Param newColorType one of: #list_of_color_types# +## + +#Return created Image_Info ## #Example -// incomplete + const int width = 256; + const int height = 128; + SkColor pixels[height][width]; + for (int y = 0; y < height; ++y) { + for (int x = 0; x < width; ++x) { + int red = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarSin((x * 4 + y) * 0.03f))); + int blue = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarCos((x * 3 + y) * 0.04f))); + int green = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarSin((x * 2 + y) * 0.05f))); + int alpha = SkScalarRoundToInt(255 * SkScalarAbs(SkScalarCos((x * 1 + y) * 0.006f))); + pixels[y][x] = + SkColorSetARGB(alpha, red * alpha / 255, green * alpha / 255, blue * alpha / 255); + } + } + SkBitmap bitmap; + SkImageInfo info = SkImageInfo::Make(width, height, kBGRA_8888_SkColorType, kPremul_SkAlphaType); + bitmap.installPixels(info, (void*) pixels, sizeof(SkColor) * width); + canvas->drawBitmap(source, 0, 0); + canvas->drawBitmap(bitmap, 0, 0); + SkImageInfo rgbaInfo = info.makeColorType(kRGBA_8888_SkColorType); + bitmap.installPixels(rgbaInfo, (void*) pixels, sizeof(SkColor) * width); + canvas->drawBitmap(bitmap, 0, 128); ## -#SeeAlso incomplete +#SeeAlso Make makeAlphaType makeColorSpace #Method ## @@ -1370,15 +1733,51 @@ but with the specified width and height. #Method SkImageInfo makeColorSpace(sk_sp cs) const #In Constructor #Line # creates Image_Info with changed Color_Space ## -#Param cs incomplete ## +Creates Image_Info with same Alpha_Type, Color_Type, width, and height, +with Color_Space set to cs. -#Return incomplete ## +#Param cs range of colors; may be nullptr ## + +#Return created Image_Info ## #Example -// incomplete +#Height 224 + const int width = 256; + const int height = 64; + auto drawLabel = [=](const char* what, bool closeToSRGB) -> void { + SkString string; + string.printf("%s gamma is %s" "close to sRGB", what, closeToSRGB ? "" : "not "); + SkPaint paint; + paint.setAntiAlias(true); + paint.setTextAlign(SkPaint::kCenter_Align); + canvas->drawString(string, width / 2, 56, paint); + }; + SkColor gradColors[] = { 0xFFFF7F00, 0xFF00FF7F, 0xFF0000FF, 0xFF7F7FFF }; + SkPoint gradPoints[] = { { 0, 0 }, { width, 0 }, { width * 2, 0 }, { width * 3, 0 } }; + SkPaint gradPaint; + gradPaint.setShader(SkGradientShader::MakeLinear(gradPoints, gradColors, nullptr, + SK_ARRAY_COUNT(gradColors), SkShader::kClamp_TileMode)); + canvas->drawRect(SkRect::MakeWH(width, height), gradPaint); + drawLabel("canvas", canvas->imageInfo().gammaCloseToSRGB()); + SkBitmap bitmap; + SkImageInfo offscreenInfo = SkImageInfo::MakeS32(width, height, kPremul_SkAlphaType); + bitmap.allocPixels(offscreenInfo); + SkCanvas sRGBOffscreen(bitmap); + sRGBOffscreen.drawRect(SkRect::MakeWH(width, height), gradPaint); + canvas->translate(0, 80); + canvas->drawBitmap(bitmap, 0, 0); + drawLabel("offscreen", offscreenInfo.gammaCloseToSRGB()); + SkImageInfo linearGamma = + offscreenInfo.makeColorSpace(offscreenInfo.colorSpace()->makeLinearGamma()); + bitmap.allocPixels(linearGamma); + SkCanvas lgOffscreen(bitmap); + lgOffscreen.drawRect(SkRect::MakeWH(width, height), gradPaint); + canvas->translate(0, 80); + canvas->drawBitmap(bitmap, 0, 0); + drawLabel("linear", linearGamma.gammaCloseToSRGB()); ## -#SeeAlso incomplete +#SeeAlso Make MakeS32 makeAlphaType makeColorType #Method ## @@ -1386,14 +1785,38 @@ but with the specified width and height. #Method int bytesPerPixel() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns number of bytes in pixel based on Color_Type ## +Returns number of bytes per pixel required by Color_Type. +Returns zero if colorType( is kUnknown_SkColorType. + +#Return bytes in pixel ## #Example -// incomplete + const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", + "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"}; + for (SkColorType colorType : { #list_of_color_types# + } ) { + SkImageInfo info = SkImageInfo::Make(1, 1, colorType, kOpaque_SkAlphaType); + SkDebugf("color: k" "%s" "_SkColorType" "%*s" "bytesPerPixel: %d\n", + colors[colorType], 13 - strlen(colors[colorType]), " ", + info.bytesPerPixel()); + } +#StdOut +color: kUnknown_SkColorType bytesPerPixel: 0 +color: kAlpha_8_SkColorType bytesPerPixel: 1 +color: kRGB_565_SkColorType bytesPerPixel: 2 +color: kARGB_4444_SkColorType bytesPerPixel: 2 +color: kRGBA_8888_SkColorType bytesPerPixel: 4 +color: kRGB_888x_SkColorType bytesPerPixel: 4 +color: kBGRA_8888_SkColorType bytesPerPixel: 4 +color: kRGBA_1010102_SkColorType bytesPerPixel: 4 +color: kRGB_101010x_SkColorType bytesPerPixel: 4 +color: kGray_8_SkColorType bytesPerPixel: 1 +color: kRGBA_F16_SkColorType bytesPerPixel: 8 +## ## -#SeeAlso incomplete +#SeeAlso width shiftPerPixel SkBitmap::bytesPerPixel #Method ## @@ -1401,11 +1824,35 @@ but with the specified width and height. #Method int shiftPerPixel() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns bit shift from pixels to bytes ## +Returns bit shift converting row bytes to row pixels. +Returns zero for kUnknown_SkColorType. + +#Return one of: 0, 1, 2, 3; left shift to convert pixels to bytes ## #Example -// incomplete + const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", + "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"}; + for (SkColorType colorType : { #list_of_color_types# + } ) { + SkImageInfo info = SkImageInfo::Make(1, 1, colorType, kOpaque_SkAlphaType); + SkDebugf("color: k" "%s" "_SkColorType" "%*s" "shiftPerPixel: %d\n", + colors[colorType], 14 - strlen(colors[colorType]), " ", + info.shiftPerPixel()); + } +#StdOut +color: kUnknown_SkColorType shiftPerPixel: 0 +color: kAlpha_8_SkColorType shiftPerPixel: 0 +color: kRGB_565_SkColorType shiftPerPixel: 1 +color: kARGB_4444_SkColorType shiftPerPixel: 1 +color: kRGBA_8888_SkColorType shiftPerPixel: 2 +color: kRGB_888x_SkColorType shiftPerPixel: 2 +color: kBGRA_8888_SkColorType shiftPerPixel: 2 +color: kRGBA_1010102_SkColorType shiftPerPixel: 2 +color: kRGB_101010x_SkColorType shiftPerPixel: 2 +color: kGray_8_SkColorType shiftPerPixel: 0 +color: kRGBA_F16_SkColorType shiftPerPixel: 3 +## ## #SeeAlso incomplete @@ -1416,14 +1863,37 @@ but with the specified width and height. #Method uint64_t minRowBytes64() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns width() times bytesPerPixel in 64 bits ## + +Returns minimum bytes per row, computed from pixel width() and Color_Type, which +specifies bytesPerPixel(). Bitmap maximum value for row bytes must be representable +as a positive value in a 32-bit signed integer. + +#Return width() times bytesPerPixel as unsigned 64-bit integer ## #Example -// incomplete + for (int shift = 24; shift < 32; ++shift) { + int width = 1 << shift; + SkImageInfo imageInfo = + SkImageInfo::Make(width, 1, kRGBA_F16_SkColorType, kPremul_SkAlphaType); + uint64_t minRowBytes = imageInfo.minRowBytes64(); + bool widthTooLarge = (uint64_t) (int32_t) minRowBytes != minRowBytes; + SkDebugf("RGBA_F16 width %d (0x%08x) %s\n", + width, width, widthTooLarge ? "too large" : "OK"); + } +#StdOut +RGBA_F16 width 16777216 (0x01000000) OK +RGBA_F16 width 33554432 (0x02000000) OK +RGBA_F16 width 67108864 (0x04000000) OK +RGBA_F16 width 134217728 (0x08000000) OK +RGBA_F16 width 268435456 (0x10000000) too large +RGBA_F16 width 536870912 (0x20000000) too large +RGBA_F16 width 1073741824 (0x40000000) too large +RGBA_F16 width -2147483648 (0x80000000) too large +## ## -#SeeAlso incomplete +#SeeAlso minRowBytes computeByteSize computeMinByteSize validRowBytes #Method ## @@ -1431,14 +1901,37 @@ but with the specified width and height. #Method size_t minRowBytes() const #In Property -#Line # incomplete ## -#Return incomplete ## +#Line # returns width() times bytesPerPixel in 32 bits ## + +Returns minimum bytes per row, computed from pixel width() and Color_Type, which +specifies bytesPerPixel(). Bitmap maximum value for row bytes must be representable +as a positive value in a 32-bit signed integer. + +#Return width() times bytesPerPixel as signed 32-bit integer ## #Example -// incomplete + for (int shift = 24; shift < 32; ++shift) { + int width = 1 << shift; + SkImageInfo imageInfo = + SkImageInfo::Make(width, 1, kRGBA_F16_SkColorType, kPremul_SkAlphaType); + size_t minRowBytes = imageInfo.minRowBytes(); + bool widthTooLarge = !minRowBytes; + SkDebugf("RGBA_F16 width %d (0x%08x) %s\n", + width, width, widthTooLarge ? "too large" : "OK"); + } +#StdOut +RGBA_F16 width 16777216 (0x01000000) OK +RGBA_F16 width 33554432 (0x02000000) OK +RGBA_F16 width 67108864 (0x04000000) OK +RGBA_F16 width 134217728 (0x08000000) OK +RGBA_F16 width 268435456 (0x10000000) too large +RGBA_F16 width 536870912 (0x20000000) too large +RGBA_F16 width 1073741824 (0x40000000) too large +RGBA_F16 width -2147483648 (0x80000000) too large +## ## -#SeeAlso incomplete +#SeeAlso minRowBytes64 computeByteSize computeMinByteSize validRowBytes #Method ## @@ -1446,15 +1939,40 @@ but with the specified width and height. #Method size_t computeOffset(int x, int y, size_t rowBytes) const #In Utility -#Line # incomplete ## -#Param x incomplete ## -#Param y incomplete ## -#Param rowBytes incomplete ## +#Line # returns byte offset within pixel array ## -#Return incomplete ## +Returns byte offset of pixel from pixel base address. + +Asserts in debug build if x or y is outside of bounds. Does not assert if +rowBytes is smaller than minRowBytes, even though result may be incorrect. + +#Param x column index, zero or greater, and less than width() ## +#Param y row index, zero or greater, and less than height() ## +#Param rowBytes size of pixel row or larger ## + +#Return offset within pixel array ## #Example -// incomplete + 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}, + { 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF}, + { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}, + { 0x00, 0x00, 0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00}, + { 0x00, 0xFF, 0x00, 0x00, 0x00, 0x00, 0xFF, 0x00}, + { 0x00, 0x00, 0xFF, 0x00, 0x00, 0xFF, 0x00, 0x00} }; + SkImageInfo imageInfo = SkImageInfo::MakeA8(8, 8); + SkBitmap bitmap; + bitmap.installPixels(imageInfo, (void*) pixels, sizeof(pixels[0])); + SkPaint paint; + paint.setColor(SK_ColorRED); + canvas->drawBitmapRect(bitmap, SkRect::MakeWH(8, 8), SkRect::MakeWH(32, 32), &paint); + size_t offset = imageInfo.computeOffset(2, 3, sizeof(pixels[0])); + pixels[0][offset] = 0x7F; + offset = imageInfo.computeOffset(5, 3, sizeof(pixels[0])); + pixels[0][offset] = 0x7F; + bitmap.installPixels(imageInfo, (void*) pixels, sizeof(pixels[0])); + canvas->drawBitmapRect(bitmap, SkRect::MakeWH(8, 8), SkRect::MakeWH(128, 128), &paint); ## #SeeAlso incomplete -- cgit v1.2.3