1Tips & FAQ
2==========
3
4+   [Gyp Options](#gypdefines)
5+   [Bitmap Subsetting](#bitmap-subsetting)
6+   [Capture a `.skp` file on a web page in Chromium](#skp-capture)
7+   [How to add hardware acceleration in Skia](#hw-acceleration)
8+   [Does Skia support Font hinting?](#font-hinting)
9+   [Does Skia shape text (kerning)?](#kerning)
10
11* * *
12
13<span id="gypdefines"></span>
14
15Gyp Options
16-----------
17
18When running `sync-and-gyp`, the `GYP_DEFINES` environment variable can
19be used to change Skia’s compile-time settings, using a
20space-separated list of key=value pairs. For example, to disable both
21the Skia GPU backend and PDF backends, run it as follows:
22
23<!--?prettify lang=sh?-->
24
25    GYP_DEFINES='skia_gpu=0 skia_pdf=0' python bin/sync-and-gyp
26    ninja -C out/Debug
27
28Note: Setting enviroment variables in the Windows CMD.EXE shell [uses a
29different syntax](/user/quick/windows#env).
30
31You can also set environment variables such as `CC`, `CXX`,
32`CFLAGS`, `CXXFLAGS`, or `CPPFLAGS` to control how Skia is compiled.
33To build with clang, for example:
34
35<!--?prettify lang=sh?-->
36
37    CC='clang' CXX='clang++' python bin/sync-and-gyp
38    ninja -C out/Debug
39
40To build with clang and enable a compiler warning for unused parameters in C++
41(but not C or assembly) code:
42
43<!--?prettify lang=sh?-->
44
45    CXXFLAGS='-Wunused-parameter' \
46        CC='clang' CXX='clang++' python bin/sync-and-gyp
47    ninja -C out/Debug
48
49
50The `GYP_GENERATORS` environment variable can be used to set the
51build systems that you want to use (as a comma-separated list).
52The default is `'ninja,msvs-ninja'` on Windows, `'ninja,xcode'` on
53Mac OS X, and just `'ninja'` on Linux.  For example, to generate
54only Ninja files on Mac:
55
56<!--?prettify lang=sh?-->
57
58    GYP_GENERATORS='ninja' python bin/sync-and-gyp
59    ninja -C out/Debug
60
61Finally, the `SKIA_OUT` environment variable can be used to set
62the path for the build directory.  The default is `out` inside the
63top-level Skia source directory.  For example to test Skia with
64two different compilers:
65
66<!--?prettify lang=sh?-->
67
68    CC='clang' CXX='clang++' SKIA_OUT=~/build/skia_clang python bin/sync-and-gyp
69    CC='gcc'   CXX='g++'     SKIA_OUT=~/build/skia_gcc   python bin/sync-and-gyp
70    ninja -C ~/build/skia_clang/Debug
71    ninja -C ~/build/skia_gcc/Debug
72
73* * *
74
75<span id="bitmap-subsetting"></span>
76
77Bitmap Subsetting
78-----------------
79
80Taking a subset of a bitmap is effectively free - no pixels are copied or
81memory is allocated. This allows Skia to offer an API that typically operates
82on entire bitmaps; clients who want to operate on a subset of a bitmap can use
83the following pattern, here being used to magnify a portion of an image with
84drawBitmapNine():
85
86    SkBitmap subset;
87    bitmap.extractSubset(&subset, rect);
88    canvas->drawBitmapNine(subset, ...);
89
90[An example](https://fiddle.skia.org/c/c91694020f0810994917b56c323e4559)
91
92* * *
93
94<span id="skp-capture"></span>
95
96Capture a `.skp` file on a web page in Chromium
97-----------------------------------------------
98
991.  Launch Chrome or Chromium with `--no-sandbox --enable-gpu-benchmarking`
1002.  Open the JS console (ctrl-shift-J)
1013.  Execute: `chrome.gpuBenchmarking.printToSkPicture('/tmp')`
102    This returns "undefined" on success.
103
104Open the resulting file in the Skia Debugger, rasterize it with `dm`,
105or use Skia's `SampleApp` to view it:
106
107<!--?prettify lang=sh?-->
108
109    bin/sync-and-gyp
110    ninja -C out/Release debugger dm SampleApp
111    out/Release/debugger /tmp/layer_0.skp &
112
113    out/Release/dm --src skp --skps /tmp/layer_0.skp -w /tmp \
114        --config 8888 gpu pdf --verbose
115    ls -l /tmp/*/skp/layer_0.skp.*
116
117    out/Release/SampleApp --picture /tmp/layer_0.skp
118
119* * *
120
121<span id="hw-acceleration"></span>
122
123How to add hardware acceleration in Skia
124----------------------------------------
125
126There are two ways Skia takes advantage of specific hardware.
127
1281.  Subclass SkCanvas
129
130    Since all drawing calls go through SkCanvas, those calls can be
131    redirected to a different graphics API. SkGLCanvas has been
132    written to direct its drawing calls to OpenGL. See src/gl/
133
1342.  Custom bottleneck routines
135
136    There are sets of bottleneck routines inside the blits of Skia
137    that can be replace on a platform in order to take advantage of
138    specific CPU features. One such example is the NEON SIMD
139    instructions on ARM v7 devices. See src/opts/
140
141* * *
142
143<span id="font-hinting"></span>
144
145Does Skia support Font hinting?
146-------------------------------
147
148Skia has a built-in font cache, but it does not know how to actual render font
149files like TrueType into its cache. For that it relies on the platform to
150supply an instance of SkScalerContext. This is Skia's abstract interface for
151communicating with a font scaler engine. In src/ports you can see support
152files for FreeType, Mac OS X, and Windows GDI font engines. Other font
153engines can easily be supported in a like manner.
154
155
156* * *
157
158<span id="kerning"></span>
159
160Does Skia shape text (kerning)?
161-------------------------------
162
163No.  Skia provides interfaces to draw glyphs, but does not implement a
164text shaper. Skia's client's often use
165[HarfBuzz](http://www.freedesktop.org/wiki/Software/HarfBuzz/) to
166generate the glyphs and their positions, including kerning.
167
168<div style="margin-bottom:99%"></div>
169