tweak SkImage documentation

- fix syntactic nits
- add how to check result of getBackendTexture
- add example

R=robertphillips@google.com
TBR=reed@google.com
Docs-Preview: https://skia.org/?cl=118590
Bug: skia:6898
Change-Id: I60cfcf448dc2f201ecc34d33ead707d0c3e3b86b
Reviewed-on: https://skia-review.googlesource.com/118590
Reviewed-by: Robert Phillips <robertphillips@google.com>
Commit-Queue: Cary Clark <caryclark@skia.org>

docs/SkImage_Reference.bmh

@@ -1395,8 +1395,11 @@ for (auto origin : { kTopLeft_GrSurfaceOrigin, kBottomLeft_GrSurfaceOrigin } ) {
 #In Property
 #Line # returns GPU reference to Image as texture ##
 
-Retrieves the backend texture. If there is none an invalid object will be returned.
+Retrieves the backend texture. If Image has no backend texture, an invalid
-If flushPendingGrContextIO is true, complete deferred I/O operations.
+object is returned. Call GrBackendTexture::isValid to determine if the result
+is valid.
+
+If flushPendingGrContextIO is true, completes deferred I/O operations.
 
 If origin in not nullptr, copies location of content drawn into Image.
 
@@ -1405,9 +1408,26 @@ If origin in not nullptr, copies location of content drawn into Image.
                kBottomLeft_GrSurfaceOrigin; or nullptr
 ##
 
-#Return back-end API texture handle. Invalid on failure. ##
+#Return back-end API texture handle; invalid on failure ##
 
-#NoExample
+#Example
+#Image 3
+#Platform gpu
+    GrContext* grContext = canvas->getGrContext();
+    if (!grContext) {
+        canvas->drawString("GPU only!", 20, 40, SkPaint());
+        return;
+    }
+    sk_sp<SkImage> imageFromBackend = SkImage::MakeFromAdoptedTexture(grContext, backEndTexture,
+            kBottomLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);
+    GrBackendTexture textureFromImage = imageFromBackend->getBackendTexture(false);
+    if (!textureFromImage.isValid()) {
+        return;
+    }
+    sk_sp<SkImage> imageFromTexture = SkImage::MakeFromAdoptedTexture(grContext, textureFromImage,
+            kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);
+    canvas->drawImage(imageFromTexture, 0, 0);
+    canvas->drawImage(imageFromBackend, 128, 128);
 ##
 
 #SeeAlso MakeFromTexture isTextureBacked

docs/undocumented.bmh

@@ -708,6 +708,8 @@ FT_Load_Glyph
 
 #Topic Texture
 #Class GrBackendTexture
+    #Method bool isValid() const
+    ##
 ##
 ##
 

include/core/SkImage.h

@@ -544,16 +544,19 @@ public:
                                      GrSurfaceOrigin* origin = nullptr) const;
 
 #if GR_TEST_UTILS
-    /** Retrieves the backend texture. If there is none an invalid object will be returned.
+    /** Retrieves the backend texture. If SkImage has no backend texture, an invalid
-        If flushPendingGrContextIO is true, complete deferred I/O operations.
+        object is returned. Call GrBackendTexture::isValid to determine if the result
+        is valid.
 
-        If origin is not nullptr, copies location of content drawn into SkImage.
+        If flushPendingGrContextIO is true, completes deferred I/O operations.
+
+        If origin in not nullptr, copies location of content drawn into SkImage.
 
         @param flushPendingGrContextIO  flag to flush outstanding requests
         @param origin                   storage for one of: kTopLeft_GrSurfaceOrigin,
                                         kBottomLeft_GrSurfaceOrigin; or nullptr
-        @return                         back-end API texture handle. Invalid on failure.
+        @return                         back-end API texture handle; invalid on failure
-     */
+    */
     GrBackendTexture getBackendTexture(bool flushPendingGrContextIO,
                                        GrSurfaceOrigin* origin = nullptr) const;
 #endif

site/user/api/SkImage_Reference.md

@@ -1444,8 +1444,11 @@ back-end API texture handle, or nullptr
 GrBackendTexture getBackendTexture(bool flushPendingGrContextIO, GrSurfaceOrigin* origin = nullptr) const
 </pre>
 
-Retrieves the backend texture. If there is none an invalid object will be returned.
+Retrieves the backend texture. If <a href="#Image">Image</a> has no backend texture, an invalid
-If <a href="#SkImage_getBackendTexture_flushPendingGrContextIO">flushPendingGrContextIO</a> is true, complete deferred I/O operations.
+object is returned. Call <a href="undocumented#GrBackendTexture_isValid">GrBackendTexture::isValid</a> to determine if the result
+is valid.
+
+If <a href="#SkImage_getBackendTexture_flushPendingGrContextIO">flushPendingGrContextIO</a> is true, completes deferred I/O operations.
 
 If <a href="#SkImage_getBackendTexture_origin">origin</a> in not nullptr, copies location of content drawn into <a href="#Image">Image</a>.
 
@@ -1461,6 +1464,12 @@ storage for one of: <a href="undocumented#kTopLeft_GrSurfaceOrigin">kTopLeft GrS
 
 ### Return Value
 
+back-end API texture handle; invalid on failure
+
+### Example
+
+<div><fiddle-embed name="d093aad721261f421c4bef4a296aab48" gpu="true"></fiddle-embed></div>
+
 ### See Also
 
 <a href="#SkImage_MakeFromTexture">MakeFromTexture</a><sup><a href="#SkImage_MakeFromTexture_2">[2]</a></sup> <a href="#SkImage_isTextureBacked">isTextureBacked</a>

site/user/api/catalog.htm

@@ -573,34 +573,6 @@
     "file": "SkCanvas_Reference",
     "name": "SkCanvas::restoreToCount",
         "stdout": "depth = 1\\ndepth = 3\\ndepth = 1\\n"
-    },
-        "SkIPoint16_Make": {
-    "code": "void draw(SkCanvas* canvas) {\n    SkIPoint16 pt1 = {45, 66};\n    SkIPoint16 pt2 = SkIPoint16::Make(45, 66);\n    SkDebugf(\"pt1.fX %c= pt2.fX\\n\", pt1.fX == pt2.fX ? '=' : '!');\n    SkDebugf(\"pt1.fY %c= pt2.fY\\n\", pt1.fY == pt2.fY ? '=' : '!');\n}",
-    "hash": "d815ca04fbf22b5acec6f85b6351f362",
-    "file": "SkIPoint16_Reference",
-    "name": "SkIPoint16::Make",
-        "stdout": "pt1.fX == pt2.fX\\npt1.fY == pt2.fY\\n"
-    },
-        "SkIPoint16_set": {
-    "code": "void draw(SkCanvas* canvas) {\n    SkIPoint16 pt1, pt2 = { SK_MinS16, SK_MaxS16 };\n    pt1.set(SK_MinS16, SK_MaxS16);\n    SkDebugf(\"pt1.fX %c= pt2.fX\\n\", pt1.fX == pt2.fX ? '=' : '!');\n    SkDebugf(\"pt1.fY %c= pt2.fY\\n\", pt1.fY == pt2.fY ? '=' : '!');\n}",
-    "hash": "abff78d3f2d97b1284ccb13d0c56b6c8",
-    "file": "SkIPoint16_Reference",
-    "name": "SkIPoint16::set()",
-        "stdout": "pt1.fX == pt2.fX\\npt1.fY == pt2.fY\\n"
-    },
-        "SkIPoint16_x": {
-    "code": "void draw(SkCanvas* canvas) {\n    SkIPoint16 pt1 = {45, 66};\n    SkDebugf(\"pt1.fX %c= pt1.x()\\n\", pt1.fX == pt1.x() ? '=' : '!');\n}",
-    "hash": "f7fd3b3674f042869de3582ab793dbf7",
-    "file": "SkIPoint16_Reference",
-    "name": "SkIPoint16::x()",
-        "stdout": "pt1.fX == pt1.x()\\n"
-    },
-        "SkIPoint16_y": {
-    "code": "void draw(SkCanvas* canvas) {\n    SkIPoint16 pt1 = {45, 66};\n    SkDebugf(\"pt1.fY %c= pt1.y()\\n\", pt1.fY == pt1.y() ? '=' : '!');\n}",
-    "hash": "3662cedaf1e9924a401f794902da3b1f",
-    "file": "SkIPoint16_Reference",
-    "name": "SkIPoint16::y()",
-        "stdout": "pt1.fY == pt1.y()\\n"
     },
         "SkIPoint_Make": {
     "code": "void draw(SkCanvas* canvas) {\n    SkIPoint pt1 = {45, 66};\n    SkIPoint pt2 = SkIPoint::Make(45, 66);\n    SkDebugf(\"pt1 %c= pt2\\n\", pt1 == pt2 ? '=' : '!');\n}",
@@ -5250,6 +5222,14 @@
     "hash": "30cee813f6aa476b0a9c8a24283e53a3",
     "file": "SkImage_Reference",
     "name": "SkImage::encodeToData_2"
+},
+    "SkImage_getBackendTexture": {
+    "code": "void draw(SkCanvas* canvas) {\n    GrContext* grContext = canvas->getGrContext();\n    if (!grContext) {\n        canvas->drawString(\"GPU only!\", 20, 40, SkPaint());\n        return;\n    }\n    sk_sp<SkImage> imageFromBackend = SkImage::MakeFromAdoptedTexture(grContext, backEndTexture,\n            kBottomLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);\n    GrBackendTexture textureFromImage = imageFromBackend->getBackendTexture(false);\n    if (!textureFromImage.isValid()) {\n        return;\n    }\n    sk_sp<SkImage> imageFromTexture = SkImage::MakeFromAdoptedTexture(grContext, textureFromImage,\n            kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);\n    canvas->drawImage(imageFromTexture, 0, 0);\n    canvas->drawImage(imageFromBackend, 128, 128);\n}",
+    "width": 256,
+    "height": 256,
+    "hash": "d093aad721261f421c4bef4a296aab48",
+    "file": "SkImage_Reference",
+    "name": "SkImage::getBackendTexture"
 },
     "SkImage_getTextureHandle": {
     "code": "void draw(SkCanvas* canvas) {\n    GrContext* context = canvas->getGrContext();\n    if (!context) {\n       return;\n    }\n    SkPaint paint;\n    paint.setAntiAlias(true);\n    SkString str;\n    int y = -10;\n    for (auto origin : { kTopLeft_GrSurfaceOrigin, kBottomLeft_GrSurfaceOrigin } ) {\n        sk_sp<SkImage> srcImage(SkImage::MakeFromTexture(context,\n                backEndTexture, origin, kN32_SkColorType, kPremul_SkAlphaType, nullptr));\n        GrSurfaceOrigin readBackOrigin;\n        GrBackendObject readBackHandle = srcImage->getTextureHandle(false, &readBackOrigin);\n        str.printf(\"readBackHandle: 0x%lx\", readBackHandle);\n        canvas->drawString(str, 5, y += 30, paint);\n        canvas->drawImage(srcImage, 80, y += 10);\n        str.printf(\"origin: k%s_GrSurfaceOrigin\", readBackOrigin ? \"BottomLeft\" : \"TopLeft\");\n        canvas->drawString(str, 5, y += srcImage->height() + 10, paint);\n    }\n}",

site/user/api/undocumented.md

@@ -910,6 +910,15 @@ Topic
 
 # <a name="GrBackendTexture"></a> Class GrBackendTexture
 
+<a name="GrBackendTexture_isValid"></a>
+## isValid
+
+<pre style="padding: 1em 1em 1em 1em;width: 62.5em; background-color: #f0f0f0">
+bool isValid() const
+</pre>
+
+---
+
 # <a name="Transfer_Mode"></a> Transfer Mode
 
 # <a name="Typeface"></a> Typeface