From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- vcl/skia/README | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 vcl/skia/README (limited to 'vcl/skia/README') 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. -- cgit v1.2.3