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>

3 files changed, 28 insertions, 30 deletions

diff --git a/site/user/api/SkImage_Reference.md b/site/user/api/SkImage_Reference.md
index 8860d6aa55..c97b0845fa 100644
--- a/site/user/api/SkImage_Reference.md
+++ b/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.
-If <a href="#SkImage_getBackendTexture_flushPendingGrContextIO">flushPendingGrContextIO</a> is true, complete deferred I/O operations.
+Retrieves the backend texture. If <a href="#Image">Image</a> has no backend texture, an invalid
+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>
diff --git a/site/user/api/catalog.htm b/site/user/api/catalog.htm
index 377a6c1b8f..902d5375bf 100644
--- a/site/user/api/catalog.htm
+++ b/site/user/api/catalog.htm
@@ -574,34 +574,6 @@
     "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}",
     "hash": "e5cf5159525bd3140f288a95fe641fae",
@@ -5251,6 +5223,14 @@
     "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}",
     "width": 256,
diff --git a/site/user/api/undocumented.md b/site/user/api/undocumented.md
index fc316b85dd..8f6d13fc3f 100644
--- a/site/user/api/undocumented.md
+++ b/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