office-gobmx/vcl/skia
Luboš Luňák 899deee845 add an extra margin to native control drawing on Skia/Mac
Some controls draw outside of their given area, which would get cropped
when first drawing to a temporary context limited to just that size.
I haven't managed to find a way to calculate the proper marging, so
just add something that's hopefully enough but not too big.

Change-Id: I1a15a3ab8cbd26cbe4fb52628b300ee70c8d51ad
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/125469
Tested-by: Jenkins
Reviewed-by: Luboš Luňák <l.lunak@collabora.com>
2021-11-18 16:44:18 +01:00
..
osx add an extra margin to native control drawing on Skia/Mac 2021-11-18 16:44:18 +01:00
win
x11 apply SAL_FORCE_HIDPI_SCALING on X11 even while drawing 2021-11-16 10:39:27 +01:00
gdiimpl.cxx Fix typos 2021-11-18 15:02:31 +01:00
README make SkiaHelper::dump() available also in non-dbgutil builds 2021-11-16 18:37:06 +01:00
salbmp.cxx try to avoid scaling bitmaps twice in Skia when drawing 2021-11-16 18:37:21 +01:00
skia_denylist_vulkan.xml
SkiaHelper.cxx Skia dumping is no longer dbgutil-only 2021-11-17 14:12:29 +01:00
zone.cxx

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.