A flush and submit apis to public headers.

We add a new flushAndSubmit() to replace the current flush() call. In
the future all other flush(GrFlushInfo) type calls will not do a
submission of work to the GPU. Instead an explicit submit call will have
to be made. flushAndSubmit will do a flush and submit.

Also adds a no-op submit call. This allows us to stage the flush submit
changes by updating all clients that use non simple flushes to add
a submit call immediately after each flush. Then we can change the logic
of where the submission happens from flush to submit without breaking
folks.

Bug: skia:10118
Change-Id: I4f02189a21912d52b888597c7734b4ca0baee792
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/289478
Commit-Queue: Greg Daniel <egdaniel@google.com>
Reviewed-by: Brian Salomon <bsalomon@google.com>

RELEASE_NOTES.txt

@@ -5,6 +5,9 @@ This file includes a list of high level updates for each milestone release.
 * * *
 
 Milestone 84
+  * Deprecate GrContext and SkSurface flush() call and replace ith with flushAndSubmit().
+    This only effects the default flush call that takes no parameters.
+    https://review.skia.org/289478
 
   * GrContext::createBackendTexture functions that initialize the texture no longer
     guarantee that all the data has been uploaded and the gpu is done with the texture.

include/core/SkSurface.h

@@ -906,13 +906,18 @@ public:
     */
     const SkSurfaceProps& props() const { return fProps; }
 
-    /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
-
-        Skia flushes as needed, so it is not necessary to call this if Skia manages
-        drawing and object lifetime. Call when interleaving Skia calls with native
-        GPU calls.
+    /** Call to ensure all reads/writes of the surface have been issued to the underlying 3D API.
+        Skia will correctly order its own draws and pixel operations. This must to be used to ensure
+        correct ordering when the surface backing store is accessed outside Skia (e.g. direct use of
+        the 3D API or a windowing system). GrContext has additional flush and submit methods that
+        apply to all surfaces and images created from a GrContext.
     */
-    void flush();
+    void flushAndSubmit();
+
+    /**
+     * Deprecated.
+     */
+    void flush() { this->flushAndSubmit(); }
 
     enum class BackendSurfaceAccess {
         kNoAccess,  //!< back-end object will not be used by client

include/gpu/GrContext.h

@@ -309,9 +309,12 @@ public:
     /**
      * Call to ensure all drawing to the context has been issued to the underlying 3D API.
      */
-    void flush() {
-        this->flush(GrFlushInfo(), GrPrepareForExternalIORequests());
-    }
+    void flushAndSubmit() { this->flush(GrFlushInfo(), GrPrepareForExternalIORequests()); }
+
+    /**
+     * Deprecated.
+     */
+    void flush() { this->flushAndSubmit(); }
 
     /**
      * Call to ensure all drawing to the context has been issued to the underlying 3D API.
@@ -376,6 +379,11 @@ public:
         return this->flush(info);
     }
 
+    /**
+     * Placeholder no-op submit call.
+     */
+    bool submit(bool syncToCpu = false);
+
     /**
      * Checks whether any asynchronous work is complete and if so calls related callbacks.
      */

src/gpu/GrContext.cpp

@@ -332,6 +332,10 @@ GrSemaphoresSubmitted GrContext::flush(const GrFlushInfo& info,
     return GrSemaphoresSubmitted::kYes;
 }
 
+bool GrContext::submit(bool syncToCpu) {
+    return true;
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 void GrContext::checkAsyncWorkCompletion() {

src/image/SkSurface.cpp

@@ -436,7 +436,7 @@ bool SkSurface::replaceBackendTexture(const GrBackendTexture& backendTexture,
                                                releaseContext);
 }
 
-void SkSurface::flush() {
+void SkSurface::flushAndSubmit() {
     this->flush(BackendSurfaceAccess::kNoAccess, GrFlushInfo());
 }