1 files changed, 87 insertions, 0 deletions
diff --git a/vcl/skia/README b/vcl/skia/README
new file mode 100644
index 000000000..63f6073ba
--- /dev/null
+++ b/vcl/skia/README
@@ -0,0 +1,87 @@
+This is code for using the Skia library as a drawing library in VCL backends.
+See external/skia for info on the library itself.
+
+Environment variables:
+======================
+
+See README.vars in the toplevel vcl/ directory. Note that many backends do not
+use Skia. E.g. on Linux it is necessary to also use SAL_USE_VCLPLUGIN=gen .
+
+There are also GUI options for controlling whether Skia is enabled.
+
+Skia drawing methods:
+=====================
+
+Skia supports several methods to draw:
+- Raster - CPU-based drawing (here primarily used for fallback when Vulkan isn't available or for debugging)
+- Vulkan - Vulkan-based GPU drawing, this is the default
+- Metal - MACOSX GPU drawing, this is the Mac default
+
+There are more (OpenGL, Metal on Mac, etc.), but (as of now) they are not supported by VCL.
+
+Logging:
+========
+
+Run LO with 'SAL_LOG=+INFO.vcl.skia' to get log information about Skia including
+tracing each drawing operation. If you want log information without drawing operations,
+use 'SAL_LOG=+INFO.vcl.skia-INFO.vcl.skia.trace'.
+
+Debugging:
+==========
+
+Both SkiaSalBitmap and SkiaSalGraphicsImpl have a dump() method that writes a PNG
+with the current contents. There is also SkiaHelper::dump() for dumping contents
+of SkBitmap, SkImage and SkSurface. You can use these in a debugger too, for example
+'p SkiaHelper::dump(image, "/tmp/a.png")'.
+
+If there is a drawing problem, you can use something like the following piece of code
+to dump an image after each relevant operation (or do it in postDraw() if you don't
+know which operation is responsible). You can then find the relevant image
+and match it with the responsible operation (run LO with 'SAL_LOG=+INFO.vcl.skia').
+
+    static int cnt = 0;
+    ++cnt;
+    char buf[100];
+    sprintf(buf,"/tmp/a%05d.png", cnt);
+    SAL_DEBUG("CNT:" << cnt);
+    if(cnt > 4000) // skip some initial drawing operations
+        dump(buf);
+
+
+Testing:
+========
+
+Currently unittests always use the 'headless' VCL backend. Use something like the following
+to run VCL unittests with Skia (and possibly skip slowcheck):
+
+SAL_SKIA=raster SAL_ENABLESKIA=1 SAL_USE_VCLPLUGIN=gen make vcl.build vcl.unitcheck vcl.slowcheck
+
+You can also use 'visualbackendtest' to visually check some operations. Use something like:
+
+SAL_SKIA=raster SAL_ENABLESKIA=1 SAL_USE_VCLPLUGIN=gen [srcdir]/bin/run visualbackendtest
+
+
+Thread safety:
+==============
+
+SolarMutex must be held for most operations (asserted in SkiaSalGraphicsImpl::preDraw() and
+in SkiaZone constructor). The reason for this is that this restriction does not appear to be
+a problem, so there's no need to verify thread safety of the code (including the Skia library).
+There's probably no fundamental reason why the code couldn't be made thread-safe.
+
+
+GrDirectContext sharing:
+========================
+
+We use Skia's sk_app::WindowContext class for creating surfaces for windows, that class
+takes care of the internals. But of offscreen drawing, we need an instance of class
+GrDirectContext. There is sk_app::WindowContext::getGrDirectContext(), but each instance creates
+its own GrDirectContext, and apparently it does not work to mix them. Which means that
+for offscreen drawing we would need to know which window (and only that window)
+the contents will be eventually painted to, which is not possible (it may not even
+be known at the time).
+
+To solve this problem we patch sk_app::WindowContext to create just one GrDirectContext object
+and share it between instances. Additionally, using sk_app::WindowContext::SharedGrDirectContext
+it is possible to share it also for offscreen drawing, including keeping proper reference
+count.