fix bookmaker return value

crosscheck in bookmaker allows
discovery of multiple errors,
but fails to return that an
error occurred.

Fix SkSurface so it is up to date with includes.
Add include parameter name in SkSurface.
Allow longer parameter descriptions.

TBR=bsalomon@google.com,rmistry@google.com
Docs-Preview: https://skia.org/?cl=88041
Bug: skia:6898
Change-Id: I9daf83f7f6753b3d1dc996a76e4693b3b8d6798c
Reviewed-on: https://skia-review.googlesource.com/88041
Reviewed-by: Brian Salomon <bsalomon@google.com>
Reviewed-by: Ravi Mistry <rmistry@google.com>
Reviewed-by: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@google.com>

1 files changed, 179 insertions, 0 deletions

diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh
index acbc191bfd..036b9b25cb 100644
--- a/docs/SkSurface_Reference.bmh
+++ b/docs/SkSurface_Reference.bmh
@@ -424,6 +424,68 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 
 # ------------------------------------------------------------------------------
 
+#Method static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
+                                                   const GrBackendTexture& backendTexture,
+                                                   GrSurfaceOrigin origin, int sampleCnt,
+                                                   SkColorType colorType,
+                                                   sk_sp<SkColorSpace> colorSpace,
+                                                   const SkSurfaceProps* surfaceProps)
+
+Wraps a GPU-backed texture into Surface. Caller must ensure the texture is
+valid for the lifetime of returned Surface. If sampleCnt greater than zero,
+creates an intermediate MSAA Surface which is used for drawing backendTexture.
+
+Surface is returned if all parameters are valid. backendTexture is valid if
+its pixel configuration agrees with colorSpace and context; for instance, if
+backendTexture has an sRGB configuration, then context must support sRGB,
+and colorSpace must be present. Further, backendTexture width and height must
+not exceed context capabilities, and the context must be able to support
+back-end textures.
+
+If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+#Param context  GPU_Context ##
+#Param backendTexture  texture residing on GPU ##
+#Param origin   one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
+#Param sampleCnt  samples per pixel, or 0 to disable full scene anti-aliasing ##
+#Param colorType  one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+                          kRGB_565_SkColorType, kARGB_4444_SkColorType,
+                          kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+                          kGray_8_SkColorType, kRGBA_F16_SkColorType
+##
+#Param colorSpace  range of colors ##
+#Param surfaceProps  LCD striping orientation and setting for device independent
+                     fonts; may be nullptr
+##
+
+#Return Surface if all parameters are valid; otherwise, nullptr ##
+
+#Example
+#ToDo  remove !fiddle below once backEndTextureRenderTarget is available ##
+#Platform !fiddle gpu cpu
+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTexture(context,
+            backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin,
+            kRGBA_8888_SkColorType, 0, nullptr, nullptr);
+    auto surfaceCanvas = gpuSurface->getCanvas();
+    surfaceCanvas->clear(SK_ColorWHITE);
+    surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
+    sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+    canvas->drawImage(image, 0, 0);
+##
+
+#SeeAlso GrBackendTexture MakeFromBackendRenderTarget MakeRenderTarget
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
 #Method static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
                                                 const GrBackendRenderTarget& backendRenderTarget,
                                                 GrSurfaceOrigin origin,
@@ -477,6 +539,66 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 
 # ------------------------------------------------------------------------------
 
+#Method static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
+                                                const GrBackendRenderTarget& backendRenderTarget,
+                                                GrSurfaceOrigin origin,
+                                                SkColorType colorType,
+                                                sk_sp<SkColorSpace> colorSpace,
+                                                const SkSurfaceProps* surfaceProps)
+
+Wraps a GPU-backed buffer into Surface. Caller must ensure render target is
+valid for the lifetime of returned Surface.
+
+Surface is returned if all parameters are valid. backendRenderTarget is valid if
+its pixel configuration agrees with colorSpace and context; for instance, if
+backendRenderTarget has an sRGB configuration, then context must support sRGB,
+and colorSpace must be present. Further, backendRenderTarget width and height must
+not exceed context capabilities, and the context must be able to support
+back-end render targets.
+
+If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+#Param context  GPU_Context ##
+#Param backendRenderTarget  GPU intermediate memory buffer ##
+#Param origin   one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
+#Param colorType  one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+                          kRGB_565_SkColorType, kARGB_4444_SkColorType,
+                          kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+                          kGray_8_SkColorType, kRGBA_F16_SkColorType
+##
+#Param colorSpace  range of colors ##
+#Param surfaceProps  LCD striping orientation and setting for device independent
+                     fonts; may be nullptr
+##
+
+#Return Surface if all parameters are valid; otherwise, nullptr ##
+
+#Example
+#ToDo  remove !fiddle below once backEndTextureRenderTarget is available ##
+#Platform !fiddle gpu
+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendRenderTarget(context,
+            backEndRenderTarget, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
+            nullptr, nullptr);
+    auto surfaceCanvas = gpuSurface->getCanvas();
+    surfaceCanvas->clear(SK_ColorWHITE);
+    surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
+    sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+    canvas->drawImage(image, 0, 0);
+##
+
+#SeeAlso MakeFromBackendTexture MakeRenderTarget
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
 #Method static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
                                                             const GrBackendTexture& backendTexture,
                                                             GrSurfaceOrigin origin,
@@ -528,6 +650,63 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 
 # ------------------------------------------------------------------------------
 
+#Method static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
+                                                            const GrBackendTexture& backendTexture,
+                                                            GrSurfaceOrigin origin,
+                                                            int sampleCnt,
+                                                            SkColorType colorType,
+                                                            sk_sp<SkColorSpace> colorSpace,
+                                                            const SkSurfaceProps* surfaceProps)
+
+Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
+a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
+the associated render target objects (but not the provided texture). Skia will not assume
+ownership of the texture and the client must ensure the texture is valid for the lifetime
+of the SkSurface.
+
+If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+#Param context  GPU_Context ##
+#Param backendTexture  texture residing on GPU ##
+#Param origin   one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
+#Param sampleCnt  samples per pixel, or 0 to disable full scene anti-aliasing ##
+#Param colorType  one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+                          kRGB_565_SkColorType, kARGB_4444_SkColorType,
+                          kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+                          kGray_8_SkColorType, kRGBA_F16_SkColorType
+##
+#Param colorSpace  range of colors ##
+#Param surfaceProps  LCD striping orientation and setting for device independent
+                     fonts; may be nullptr
+##
+
+#Return Surface if all parameters are valid; otherwise, nullptr ##
+
+#Example
+#Platform !fiddle gpu
+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTextureAsRenderTarget(
+            context, backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0,
+            kRGBA_8888_SkColorType, nullptr, nullptr);
+    auto surfaceCanvas = gpuSurface->getCanvas();
+    surfaceCanvas->clear(SK_ColorWHITE);
+    surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
+    sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+    canvas->drawImage(image, 0, 0);
+##
+
+#SeeAlso MakeFromBackendRenderTarget MakeRenderTarget
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
 #Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
                                              const SkImageInfo& imageInfo,
                                              int sampleCount, GrSurfaceOrigin surfaceOrigin,