Skia – API Reference and Overview

Docs: SkCanvas Overview

Mon, 01 Jan 0001 00:00:00 +0000

The drawing context

Preview

Here is an example of a set of drawing commands to draw a filled heptagram. This function can be cut and pasted into fiddle.skia.org.

Details

SkCanvas is the drawing context for Skia. It knows where to direct the drawing (i.e. where the screen of offscreen pixels are), and maintains a stack of matrices and clips. Note however, that unlike similar contexts in other APIs like postscript, cairo, or awt, Skia does not store any other drawing attributes in the context (e.g. color, pen size). Rather, these are specified explicitly in each draw call, via a SkPaint.

The code above will draw a rectangle rotated by 45 degrees. Exactly what color and style the rect will be drawn in is described by the paint, not the canvas.

Check out more detailed info on creating a SkCanvas object.

To begin with, we might want to erase the entire canvas. We can do this by drawing an enormous rectangle, but there are easier ways to do it.

void draw(SkCanvas* canvas) {
    SkPaint paint;
    paint.setColor(SK_ColorWHITE);
    canvas->drawPaint(paint);
}

This fills the entire canvas (though respecting the current clip of course) with whatever color or shader (and xfermode) is specified by the paint. If there is a shader in the paint, then it will respect the current matrix on the canvas as well (see SkShader). If you just want to draw a color (with an optional xfermode), you can just call drawColor(), and save yourself having to allocate a paint.

void draw(SkCanvas* canvas) {
    canvas->drawColor(SK_ColorWHITE);
}

All of the other draw APIs are similar, each one ending with a paint parameter.

In some of the calls, we pass a pointer, rather than a reference, to the paint. In those instances, the paint parameter may be null. In all other cases the paint parameter is required.

Next: SkPaint

Docs: SkCanvas Creation

Mon, 01 Jan 0001 00:00:00 +0000

First, read about the SkCanvas API.

Skia has multiple backends which receive SkCanvas drawing commands. Each backend has a unique way of creating a SkCanvas. This page gives an example for each:

Raster

The raster backend draws to a block of memory. This memory can be managed by Skia or by the client.

The recommended way of creating a canvas for the Raster and Ganesh backends is to use a SkSurface, which is an object that manages the memory into which the canvas commands are drawn.

#include "include/core/SkData.h"
#include "include/core/SkImage.h"
#include "include/core/SkStream.h"
#include "include/core/SkSurface.h"
void raster(int width, int height,
            void (*draw)(SkCanvas*),
            const char* path) {
    sk_sp<SkSurface> rasterSurface =
            SkSurfaces::Raster(SkImageInfo::MakeN32Premul(width, height));
    SkCanvas* rasterCanvas = rasterSurface->getCanvas();
    draw(rasterCanvas);
    sk_sp<SkImage> img(rasterSurface->makeImageSnapshot());
    if (!img) { return; }
    sk_sp<SkData> png = SkPngEncoder::Encode(nullptr, img, {});
    if (!png) { return; }
    SkFILEWStream out(path);
    (void)out.write(png->data(), png->size());
}

Alternatively, we could have specified the memory for the surface explicitly, instead of asking Skia to manage it.

#include <vector>
#include "include/core/SkSurface.h"
std::vector<char> raster_direct(int width, int height,
                                void (*draw)(SkCanvas*)) {
    SkImageInfo info = SkImageInfo::MakeN32Premul(width, height);
    size_t rowBytes = info.minRowBytes();
    size_t size = info.getSafeSize(rowBytes);
    std::vector<char> pixelMemory(size);  // allocate memory
    sk_sp<SkSurface> surface =
            SkSurfaces::WrapPixels(
                    info, &pixelMemory[0], rowBytes);
    SkCanvas* canvas = surface->getCanvas();
    draw(canvas);
    return pixelMemory;
}

GPU

GPU Surfaces must have a GrContext object which manages the GPU context, and related caches for textures and fonts. GrContexts are matched one to one with OpenGL contexts or Vulkan devices. That is, all SkSurfaces that will be rendered to using the same OpenGL context or Vulkan device should share a GrContext. Skia does not create a OpenGL context or Vulkan device for you. In OpenGL mode it also assumes that the correct OpenGL context has been made current to the current thread when Skia calls are made.

#include "include/gpu/ganesh/GrDirectContext.h"
#include "include/gpu/ganesh/gl/GrGLInterface.h"
#include "include/gpu/ganesh/SkSurfaceGanesh.h"
#include "include/core/SkData.h"
#include "include/core/SkImage.h"
#include "include/core/SkStream.h"
#include "include/core/SkSurface.h"

void gl_example(int width, int height, void (*draw)(SkCanvas*), const char* path) {
    // You've already created your OpenGL context and bound it.
    sk_sp<const GrGLInterface> interface = nullptr;
    // Leaving interface as null makes Skia extract pointers to OpenGL functions for the current
    // context in a platform-specific way. Alternatively, you may create your own GrGLInterface
    // and initialize it however you like to attach to an alternate OpenGL implementation or
    // intercept Skia's OpenGL calls.
    sk_sp<GrDirectContext> context = GrDirectContexts::MakeGL(interface);
    SkImageInfo info = SkImageInfo:: MakeN32Premul(width, height);
    sk_sp<SkSurface> gpuSurface(
            SkSurfaces::RenderTarget(context.get(), skgpu::Budgeted::kNo, info));
    if (!gpuSurface) {
        SkDebugf("SkSurfaces::RenderTarget returned null\n");
        return;
    }
    SkCanvas* gpuCanvas = gpuSurface->getCanvas();
    draw(gpuCanvas);
    sk_sp<SkImage> img(gpuSurface->makeImageSnapshot());
    if (!img) { return; }
    // Must pass non-null context so the pixels can be read back and encoded.
    sk_sp<SkData> png = SkPngEncoder::Encode(context.get(), img, {});
    if (!png) { return; }
    SkFILEWStream out(path);
    (void)out.write(png->data(), png->size());
}

SkPDF

The SkPDF backend uses SkDocument instead of SkSurface, since a document must include multiple pages.

#include "include/docs/SkPDFDocument.h"
#include "include/core/SkStream.h"
void skpdf(int width, int height,
           void (*draw)(SkCanvas*),
           const char* path) {
    SkFILEWStream pdfStream(path);
    auto pdfDoc = SkPDF::MakeDocument(&pdfStream);
    SkCanvas* pdfCanvas = pdfDoc->beginPage(SkIntToScalar(width),
                                            SkIntToScalar(height));
    draw(pdfCanvas);
    pdfDoc->close();
}

SkPicture

The SkPicture backend uses SkPictureRecorder instead of SkSurface.

#include "include/core/SkPictureRecorder.h"
#include "include/core/SkPicture.h"
#include "include/core/SkStream.h"
void picture(int width, int height,
             void (*draw)(SkCanvas*),
             const char* path) {
    SkPictureRecorder recorder;
    SkCanvas* recordingCanvas = recorder.beginRecording(SkIntToScalar(width),
                                                        SkIntToScalar(height));
    draw(recordingCanvas);
    sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
    SkFILEWStream skpStream(path);
    // Open SKP files with `viewer --skps PATH_TO_SKP --slide SKP_FILE`
    picture->serialize(&skpStream);
}

NullCanvas

The null canvas is a canvas that ignores all drawing commands and does nothing.

#include "include/utils/SkNullCanvas.h"
void null_canvas_example(int, int, void (*draw)(SkCanvas*), const char*) {
    std::unique_ptr<SkCanvas> nullCanvas = SkMakeNullCanvas();
    draw(nullCanvas.get());  // NoOp
}

SkXPS

The (still experimental) SkXPS canvas writes into an XPS document.

#include "include/core/SkDocument.h"
#include "include/core/SkStream.h"
#ifdef SK_BUILD_FOR_WIN
void skxps(IXpsOMObjectFactory* factory;
           int width, int height,
           void (*draw)(SkCanvas*),
           const char* path) {
    SkFILEWStream xpsStream(path);
    sk_sp<SkDocument> xpsDoc = SkDocument::MakeXPS(&pdfStream, factory);
    SkCanvas* xpsCanvas = xpsDoc->beginPage(SkIntToScalar(width),
                                            SkIntToScalar(height));
    draw(xpsCanvas);
    xpsDoc->close();
}
#endif

SkSVG

The (still experimental) SkSVG canvas writes into an SVG document.

#include "include/core/SkStream.h"
#include "include/svg/SkSVGCanvas.h"
#include "SkXMLWriter.h"
void sksvg(int width, int height,
           void (*draw)(SkCanvas*),
           const char* path) {
    SkFILEWStream svgStream(path);
    std::unique_ptr<SkXMLWriter> xmlWriter(
            new SkXMLStreamWriter(&svgStream));
    SkRect bounds = SkRect::MakeIWH(width, height);
    std::unique_ptr<SkCanvas> svgCanvas =
        SkSVGCanvas::Make(bounds, xmlWriter.get());
    draw(svgCanvas.get());
}

Example

To try this code out, make a new unit test using instructions here and wrap these functions together:

#include "include/core/SkCanvas.h"
#include "include/core/SkPath.h"
#include "tests/Test.h"
void example(SkCanvas* canvas) {
    const SkScalar scale = 256.0f;
    const SkScalar R = 0.45f * scale;
    const SkScalar TAU = 6.2831853f;
    SkPath path;
    for (int i = 0; i < 5; ++i) {
        SkScalar theta = 2 * i * TAU / 5;
        if (i == 0) {
            path.moveTo(R * cos(theta), R * sin(theta));
        } else {
            path.lineTo(R * cos(theta), R * sin(theta));
        }
    }
    path.close();
    SkPaint p;
    p.setAntiAlias(true);
    canvas->clear(SK_ColorWHITE);
    canvas->translate(0.5f * scale, 0.5f * scale);
    canvas->drawPath(path, p);
}
DEF_TEST(FourBackends, r) {
    raster(     256, 256, example, "out_raster.png" );
    gl_example( 256, 256, example, "out_gpu.png"    );
    skpdf(      256, 256, example, "out_skpdf.pdf"  );
    picture(    256, 256, example, "out_picture.skp");
}

Docs: SkBlendMode Overview

Mon, 01 Jan 0001 00:00:00 +0000

Describes how destination pixel is replaced with a combination of itself and source pixel. Blend_Mode may use source, destination, or both. Blend_Mode may operate on each Color component independently, or may allow all source pixel components to contribute to one destination pixel component.

Blend_Mode does not use adjacent pixels to determine the outcome.

Blend_Mode uses source and read destination Alpha to determine written destination Alpha; both source and destination Alpha may also affect written destination Color components.

Regardless of how Alpha is encoded in source and destination pixel, nearly all Color_Types treat it as ranging from zero to one. And, nearly all Blend_Mode algorithms limit the output so that all results are also zero to one.

Two exceptions are SkBlendMode::kPlus and kRGBA_F16_SkColorType.

SkBlendMode::kPlus permits computing Alpha and Color component values larger than one. For Color_Types other than kRGBA_F16_SkColorType, resulting Alpha and component values are clamped to one.

kRGBA_F16_SkColorType permits values outside the zero to one range. It is up to the client to ensure that the result is within the range of zero to one, and therefore well-defined.

Compositing Digital Images describes Porter_Duff modes SkBlendMode::kClear through SkBlendMode::kXor.

Drawing a bitmap with transparency using Porter_Duff compositing is free to clear the destination.

Draw geometry with transparency using Porter_Duff compositing does not combine transparent source pixels, leaving the destination outside the geometry untouched.

Modes SkBlendMode::kPlus and SkBlendMode::kScreen use simple arithmetic to lighten or darken the destination. Modes SkBlendMode::kOverlay through SkBlendMode::kMultiply use more complicated algorithms to lighten or darken; sometimes one mode does both, as described by Blend Modes .

SkBlendMode::kModulate is a mashup of SkBlendMode::kSrcATop and SkBlendMode::kMultiply. It multiplies all components, including Alpha; unlike SkBlendMode::kMultiply, if either source or destination is transparent, result is transparent. SkBlendMode::kModulate uses Premultiplied values to compute the product; SkBlendMode::kMultiply uses Unpremultiplied values to compute the product.

Modes SkBlendMode::kHue, SkBlendMode::kSaturation, SkBlendMode::kColor, and SkBlendMode::kLuminosity convert source and destination pixels using all components color information, using non-separable blend modes .

Docs: SkPath Overview

Mon, 01 Jan 0001 00:00:00 +0000

Path contains Lines and Curves which can be stroked or filled. Contour is composed of a series of connected Lines and Curves. Path may contain zero, one, or more Contours. Each Line and Curve are described by Verb, Points, and optional Path_Conic_Weight.

Each pair of connected Lines and Curves share common Point; for instance, Path containing two connected Lines are described the Path_Verb sequence: SkPath::kMove_Verb, SkPath::kLine_Verb, SkPath::kLine_Verb; and a Point sequence with three entries, sharing the middle entry as the end of the first Line and the start of the second Line.

Path components Arc, Rect, Round_Rect, Circle, and Oval are composed of Lines and Curves with as many Verbs and Points required for an exact description. Once added to Path, these components may lose their identity; although Path can be inspected to determine if it describes a single Rect, Oval, Round_Rect, and so on.

Example

Path contains three Contours: Line, Circle, and Quad. Line is stroked but not filled. Circle is stroked and filled; Circle stroke forms a loop. Quad is stroked and filled, but since it is not closed, Quad does not stroke a loop.

Path contains a Path_Fill_Type which determines whether overlapping Contours form fills or holes. Path_Fill_Type also determines whether area inside or outside Lines and Curves is filled.

Example

Path is drawn filled, then stroked, then stroked and filled.

Path contents are never shared. Copying Path by value effectively creates a new Path independent of the original. Internally, the copy does not duplicate its contents until it is edited, to reduce memory use and improve performance.

Contour contains one or more Verbs, and as many Points as are required to satisfy Path_Verb_Array. First Path_Verb in Path is always SkPath::kMove_Verb; each SkPath::kMove_Verb that follows starts a new Contour.

Example

Each SkPath::moveTo starts a new Contour, and content after SkPath::close() also starts a new Contour. Since SkPath::conicTo is not preceded by SkPath::moveTo, the first Point of the third Contour starts at the last Point of the second Contour.

If final Path_Verb in Contour is SkPath::kClose_Verb, Line connects Path_Last_Point in Contour with first Point. A closed Contour, stroked, draws Paint_Stroke_Join at Path_Last_Point and first Point. Without SkPath::kClose_Verb as final Verb, Path_Last_Point and first Point are not connected; Contour remains open. An open Contour, stroked, draws Paint_Stroke_Cap at Path_Last_Point and first Point.

Example

Path is drawn stroked, with an open Contour and a closed Contour.

Contour length is distance traveled from first Point to Path_Last_Point, plus, if Contour is closed, distance from Path_Last_Point to first Point. Even if Contour length is zero, stroked Lines are drawn if Paint_Stroke_Cap makes them visible.

Example

Docs: SkPaint Overview

Mon, 01 Jan 0001 00:00:00 +0000

Anytime you draw something in Skia, and want to specify what color it is, or how it blends with the background, or what style or font to draw it in, you specify those attributes in a paint.

Unlike SkCanvas, paints do not maintain an internal stack of state (i.e. there is no save/restore on a paint). However, paints are relatively light-weight, so the client may create and maintain any number of paint objects, each set up for a particular use. Factoring all of these color and stylistic attributes out of the canvas state, and into (multiple) paint objects, allows canvas' save/restore to be that much more efficient, as all they have to do is maintain the stack of matrix and clip settings.

This shows three different paints, each set up to draw in a different style. Now the caller can intermix these paints freely, either using them as is, or modifying them as the drawing proceeds.

Beyond simple attributes such as color, strokes, and text values, paints support effects. These are subclasses of different aspects of the drawing pipeline, that when referenced by a paint (each of them is reference-counted), are called to override some part of the drawing pipeline.

For example, to draw using a gradient instead of a single color, assign a SkShader to the paint.

Now, anything drawn with that paint will be drawn with the gradient specified in the call to MakeLinear(). The shader object that is returned is reference-counted. Whenever any effects object, like a shader, is assigned to a paint, its reference-count is increased by the paint. To balance this, the caller in the above example calls unref() on the shader once it has assigned it to the paint. Now the paint is the only “owner” of that shader, and it will automatically call unref() on the shader when either the paint goes out of scope, or if another shader (or null) is assigned to it.

There are 6 types of effects that can be assigned to a paint:

SkPathEffect - modifications to the geometry (path) before it generates an alpha mask (e.g. dashing)
SkRasterizer - composing custom mask layers (e.g. shadows)
SkMaskFilter - modifications to the alpha mask before it is colorized and drawn (e.g. blur)
SkShader - e.g. gradients (linear, radial, sweep), bitmap patterns (clamp, repeat, mirror)
SkColorFilter - modify the source color(s) before applying the blend (e.g. color matrix)
SkBlendMode - e.g. porter-duff transfermodes, blend modes

Paints also hold a reference to a SkTypeface. The typeface represents a specific font style, to be used for measuring and drawing text. Speaking of which, paints are used not only for drawing text, but also for measuring it.

paint.measureText(...);
paint.getTextBounds(...);
paint.textToGlyphs(...);
paint.getFontMetrics(...);

SkBlendMode

The following example demonstrates all of the Skia’s standard blend modes. In this example the source is a solid magenta color with a horizontal alpha gradient and the destination is a solid cyan color with a vertical alpha gradient.

SkShader

Several shaders are defined (besides the linear gradient already mentioned):

Bitmap Shader
Radial Gradient Shader
Two-Point Conical Gradient Shader
Sweep Gradient Shader
Fractal Perlin Noise Shader
Turbulence Perlin Noise Shader
Compose Shader

SkMaskFilter

Blur Mask Filter

SkColorFilter

Color Matrix Color Filter
Color Table Color Filter

SkPathEffect

SkPath2DPathEffect: Stamp the specified path to fill the shape, using the matrix to define the latice.
SkLine2DPathEffect: a special case of SkPath2DPathEffect where the path is a straight line to be stroked, not a path to be filled.
SkPath1DPathEffect: create dash-like effects by replicating the specified path along the drawn path.
SkCornerPathEffect: a path effect that can turn sharp corners into various treatments (e.g. rounded corners).
SkDashPathEffect: a path effect that implements dashing.
SkDiscretePathEffect: This path effect chops a path into discrete segments, and randomly displaces them.
SkComposePathEffect: a pathEffect whose effect is to apply first the inner pathEffect and the the outer pathEffect (i.e. outer(inner(path))).
SkSumPathEffect: a pathEffect whose effect is to apply two effects, in sequence (i.e. first(path) + second(path)).