Public API Classes

kStroke

class kStroke : public impl::kStrokeBase
{
public:
    kStroke(
        kStrokeStyle style,
        kScalar dashoffset = 0,
        const kScalar *strokes = nullptr, size_t count = 0
    );

    kStroke(
        kStrokeStyle style,
        kLineJoin join,
        kCapStyle startcap = kCapStyle::Flat,
        kCapStyle endcap = kCapStyle::Flat,
        kCapStyle dashcap = kCapStyle::Flat,
        kScalar dashoffset = 0,
        const kScalar *strokes = nullptr, size_t count = 0
    );

    ~kStroke();

    kStroke(const kStroke &source);
    kStroke& operator=(const kStroke &source);
};

kStroke is a shareable resource object which holds properties for stroke paint operation. It's used as a source for kPen objects (which fully define line painting style).

Methods

kStroke(kStrokeStyle style, kScalar dashoffset, const kScalar *strokes, size_t count)

Construct kStroke object with given stroke style and dash offset.
style - defines stroke style.
dashoffset - defines dash offset value for dash patterns.
strokes - pointer to array of kScalar values which define custom stroke style.
count - number of elements in the strokes array.

strokes and count parameters are ignored for stroke styles other than Custom. For Custom stroke style these parameters must be valid.

Line join style is set to Miter. line start cap, end cap and dash cap styles are set to Flat.

kStroke(
    kStrokeStyle style, kLineJoin join,
    kCapStyle startcap, kCapStyle endcap, kCapStyle dashcap,
    kScalar dashoffset, const kScalar *strokes, size_t count
)

Construct kStroke object with every parameter specified.
style - defines stroke style.
join - defines line join style.
startcap - defines style for line starting cap.
endcap - defines style for line ending cap.
dashcap - defines style for dash caps (caps at the endings of individual stroke segments).
dashoffset - defines dash offset value for dash patterns.
strokes - pointer to array of kScalar values which define custom stroke style.
count - number of elements in the strokes array.

strokes and count parameters are ignored for stroke styles other than Custom. For Custom stroke style these parameters must be valid.

Examples

Basic usage of kStroke object can be seen in stroke styles and pens example.

kGradient

class kGradient
{
public:
    kGradient(
        const kColor start, const kColor end,
        kExtendType extend = kExtendType::Clamp
    );

    kGradient(
        const kGradientStop *stops, size_t count,
        kExtendType extend = kExtendType::Clamp
    );

    ~kGradient();

private:
    kGradient(const kGradient &source);
    kGradient& operator=(const kGradient &source);
};

kGradient is a unique resource object which defines gradient colors at certain positions.

Methods

kGradient(const kColor start, const kColor end, kExtendType extend)

Construct simple gradient with two colors at 0.0 and 1.0 stops.
start - color at 0.0 stop.
end - color at 1.0 stop.
extend - gradient extend type.

kGradient(const kGradientStop *stops, size_t count, kExtendType extend)

Construct gradient with multiple stops.
stops - pointer to array of kGradientStop values.
count - number of elements in stops array.
extend - gradient extend type.
After object construction stops array can be safely deleted.

Examples

Basic usage of kGradient object can be seen in gradients and gradient brushes example.

kPen

class kPen : public impl::kPenBase
{
public:
    kPen();

    kPen(
        const kColor color, kScalar width = 1, kStrokeStyle style = kStrokeStyle::Solid,
        const kScalar *strokes = nullptr, size_t count = 0
    );

    kPen(const kColor color, kScalar width, const kStroke &stroke);
    kPen(const kBrush &brush, kScalar width, const kStroke &stroke);

    ~kPen();

    kPen(const kPen &source);
    kPen& operator=(const kPen &source);
};

kPen is a shareable resource object. It completely defines line painting style: its width, stroke style (via kStroke object) and paint appearance (via kBrush object). kPen ties together kStroke and kBrush objects, pen object manages references to internal stroke and brush resources. After pen object construction stroke and brush objects used to create a pen can be safely deleted if they are no longer needed as separate entities.

Methods

kPen()

Construct "clear" pen with implicitly created stroke object with kStrokeStyle::Clear style. Use this kind of pen object to disable line painting.

kPen(
    const kColor color, kScalar width, kStrokeStyle style,
    const kScalar *strokes, size_t count
)

Construct pen object with implicitly created stroke object with given style and solid brush with given color.
color - color for implicitly created solid brush object. This will be the line color.
width - line width.
style - stroke style for implicitly created stroke object. This will be the line stroke style.
strokes - pointer to array of kScalar values which define custom stroke style.
count - number of elements in the strokes array.

strokes and count parameters are ignored for stroke styles other than Custom. For Custom stroke style these parameters must be valid.

kPen(const kColor color, kScalar width, const kStroke &stroke)

Construct pen object based on existing kStroke object and implicitly created solid brush with given color.
color - color for implicitly created solid brush object. This will be the line color.
width - line width.
stroke - stroke object which completely defines line stroke style.

kPen(const kBrush &brush, kScalar width, const kStroke &stroke)

Construct pen object based on existing kBrush and kStroke objects.
brush - brush object which completely defines line paint style.
width - line width.
stroke - stroke object which completely defines line stroke style.

Examples

Basic pen usage with shapes shown in basic shapes example.
Some advanced pen usage shown in stroke styles and pens example.

kBrush

class kBrush : public impl::kBrushBase
{
public:
    kBrush();
    kBrush(const kColor color);
    kBrush(const kPoint &start, const kPoint &end, const kGradient &gradient);

    kBrush(
        const kPoint &center, const kPoint &offset, const kSize &radius,
        const kGradient &gradient
    );

    kBrush(kExtendType xextend, kExtendType yextend, const kBitmap &bitmap);

    ~kBrush();

    kBrush(const kBrush &source);
    kBrush& operator=(const kBrush &source);
};

kBrush is a shareable resource object. It completely defines fill style and color for lines (when used with kPen) and closed shapes (when used as source for any shape fill method). Brush object has its style property of type kBrushStyle. This property is implicitly set by appropriate brush constructor. Brush object manages references to internal gradient and bitmap resources. After brush object construction gradient or bitmap object used to create a brush can be safely deleted if they are no longer needed as separate entities.

Methods

kBrush()

Construct "clear" brush (brush style is set to kBrushStyle::Clear). Use this kind of brush object to disable fill.

kBrush(const kColor color)

Construct solid brush with given color (brush style is set to kBrushStyle::Solid).
color - color which will be used for solid fill.

kBrush(const kPoint &start, const kPoint &end, const kGradient &gradient)

Construct linear gradient brush (brush style is set to kBrushStyle::LinearGradient).
start - starting point for a gradient line (here will be color placed at 0.0 gradient stop).
end - ending point for a gradient line (here will be color placed at 1.0 gradient stop).
gradient - kGradient object which defines gradient colors.

kBrush(
    const kPoint &center, const kPoint &offset, const kSize &radius,
    const kGradient &gradient
)

Construct radial gradient brush (brush style is set to kBrushStyle::RadialGradient).
center - center point of gradient enclosing ellipse.
offset - offset of actual gradient center where color at 0.0 stop location will be placed.
radius - enclosing ellipse radiuses.
gradient - kGradient object which defines gradient colors.

kBrush(kExtendType xextend, kExtendType yextend, const kBitmap &bitmap)

Construct bitmap (texture) brush (brush style is set to kBrushStyle::Bitmap).
xextend - extend along x bitmap axis.
yextend - extend along y bitmap axis.
bitmap - kBitmap object which defines fill pattern (texture).

Examples

Basic brush usage with shapes shown in basic filled shapes example.
Gradient brushes shown in gradients and gradient brushes example.
Bitmap brush usage shown in bitmaps example.

kFont

class kFont : public impl::kFontBase
{
public:
    kFont();
    kFont(const char *facename, kScalar size, uint32_t style = 0);

    ~kFont();

    kFont(const kFont &source);
    kFont& operator=(const kFont &source);
};

kFont is a shareable resource object. It defines font properties for text rendering.

Methods

kFont()

Construct font object with system's default font and default properties. Resulting font face name, style and size are implementation dependent and even may not correspond to system settings.

This behaviour is subject to change

kFont(const char *facename, kScalar size, uint32_t style)

Construct font object with given face name, size and style. Depending on implementation system's font mapper can be used to match font names for non existent fonts.
facename - font face name.
size - font size in points (1/72 inch).
style - combination of kFontStyle flags.

Examples

Basic font usage shown in text and fonts example.

kPath

class kPath
{
private:
    class Constructor
    {
    public:
        Constructor& MoveTo(const kPoint &point);
        Constructor& LineTo(const kPoint &point);
        Constructor& BezierTo(const kPoint &p1, const kPoint &p2, const kPoint &p3);
        Constructor& ArcTo(const kRect &rect, kScalar start, kScalar end);
        Constructor& PolyLineTo(const kPoint *points, size_t count);
        Constructor& PolyBezierTo(const kPoint *points, size_t count);
        Constructor& Text(
            const char *text, int count, const kFont &font,
            kTextOrigin origin = kTextOrigin::Top
        );
        Constructor& Close();

        impl::kPathImpl* Build();
    };

public:
    kPath(impl::kPathImpl *result);
    kPath(const kPath &source, const kTransform &transform);
    ~kPath();

    static Constructor Create();

private:
    kPath();
    kPath(const kPath &source);
    kPath& operator=(const kPath &source);
};

kPath is a unique resource object. It defines arbitrary shape of any complexity. Path object does not store any "style" information for shape stroking or filling.

Operation

To create new path object one must use Constructor helper class. Call Create() static function of kPath class to return new path constructor instance and then chain sequence of path construction commands. To build actual kPath object use constructor's Build() call and pass its result to kPath constructor or assign it to newly declared kPath variable.

Methods

kPath(impl::kPathImpl *result)

Create path object based on newly constructed path. After construction path object is ready for use by painting commands.
result - constructed intermediate path object returned by path constructor's Build() call.

kPath(const kPath &source, const kTransform &transform)

Construct transformed copy of a given path. After copy construction path is ready for use by painting commands.
source - source path object, should be in commited state.
transform - transformation matrix by which all source path vertices will be transformed.

static Constructor Create();

Create new path constructor helper object to build new path.

Constructor& Constructor::MoveTo(const kPoint &point)

Moves current position to given point. This command starts new shape without closing any previously defined shape. This is a shape definition method.
point - new location for current position.

Constructor& Constructor::LineTo(const kPoint &point)

Adds straight line segment from current position to given point and moves current position to that point. This command continues current shape. This is a shape definition method.
point - line ending point.

Constructor& Constructor::BezierTo(const kPoint &p1, const kPoint &p2, const kPoint &p3)

Adds cubic bezier line segment to current shape starting with current position. This command continues current shape. This is a shape definition method.
p1 - first control point.
p2 - second control point.
p3 - line ending point. Becomes new current position.

Constructor& Constructor::ArcTo(const kRect &rect, kScalar start, kScalar end)

Adds arc segment to current shape. This command continues current shape. Current position is moved to arc ending point. This is a shape definition method.

Parameters to this command are subject to change. Currently they are inconsistent with "current position" notation.

rect - arc ellipse bounding rectangle.
start - arc starting angle in degrees.
end - arc ending angle in degrees.

Constructor& Constructor::PolyLineTo(const kPoint *points, size_t count)

Adds multiple straight line segments connected together from current position and moves current position to last given point. This command continues current shape. This is a shape definition method.
points - pointer to kPoint array.
count - number of points in points array.

Constructor& Constructor::PolyBezierTo(const kPoint *points, size_t count)

Adds multiple cubic bezier line segments connected together starting at current position and moves current position to last given point. This command continues current shape. This is a shape definition method.
points - pointer to kPoint array. Every three points defines one segment treating previous point as a first point of new segment.
count - number of points in points array, should be multiple of 3.

Constructor& Constructor::Text(
    const char *text, int count, const kFont &font,
    kTextOrigin origin
)

Adds text shape to a path originating at current position. This command starts new shape without closing any previously defined shape. This is a shape definition method.
text - pointer to character string.
count - number of bytes in a string, set to -1 if text string is null terminated string.
font - font with which glyphs shapes will be defined.
origin - text shape origin relative to current position.

Constructor& Constructor::Close()

Close current shape (by optionally adding closing straight line segment to shape starting point from current position). New shape starts after this command execution with current position set to current shape starting point. This is a shape definition method.

Constructor& Constructor::Build()

Commit path construction and returns intermediate object for actual kPath object construction.

Examples

Basic path usage shown in paths example.

kBitmap

class kBitmap
{
public:
    kBitmap(size_t width, size_t height, kBitmapFormat format);
    ~kBitmap();

    size_t width() const;
    size_t height() const;
    kSize size() const;
    kBitmapFormat format() const;

    void Update(
        const kRectInt *updaterect, kBitmapFormat sourceformat,
        size_t sourcepitch, void *data
    );

private:
    kBitmap(const kBitmap &source);
    kBitmap& operator=(const kBitmap &source);
};

kBitmap is a unique resource object. Bitmap stores color or monochrome image data. Only two formats are supported: 32-bit premultiplied color with alpha channel and 8-bit grayscale images. Grayscale images can be used as a mask for fill and painting operations. Once created bitmap properties can not be changed, only bitmap data can be changed. Bitmap object can be a destination for canvas painting via kBitmapCanvas class.

Methods

kBitmap(size_t width, size_t height, kBitmapFormat format)

Construct empty bitmap with specified properties.
width - image width in pixels.
height - image height in pixels.
format - image format.

void Update(
    const kRectInt *updaterect, kBitmapFormat sourceformat,
    size_t sourcepitch, void *data
)

Update whole or part of image data from external memory source.
updaterect - optional rectangle which defines portion of image data for update.
sourceformat - source data format, should match bitmap object's format.
sourcepitch - number of bytes between rows in source data.
data - pointer to raw image data.
Source data format should be fully identical to format that was specified when bitmap object was constructed. For kBitmapFormat::Color32BitAlphaPremultiplied it should be BGRA premultiplied data, for kBitmapFormat::Mask8Bit it should be 8-bit grayscale data. This method does not perform any data format conversion. If updaterect is specified it's clipped against bitmap dimensions.

Examples

Basic bitmaps usage shown in bitmaps example.

kTextService

class kTextService
{
public:
    kTextService();
    ~kTextService();

    void GetFontMetrics(const kFont &font, kFontMetrics &metrics);

    void GetGlyphMetrics(
        const kFont &font, size_t first, size_t last,
        kGlyphMetrics *metrics
    );

    kSize TextSize(
        const char *text, int count, const kFont &font,
        const kTextSizeProperties *properties = nullptr, kRect *bounds = nullptr
    );

private:
    kTextService(const kTextService &source);
    kTextService& operator=(const kTextService &source);
};

kTextService class defines methods for font and text measurement. If you need to get font metrics or measure text without having any target for canvas instantiation you can use kTextService object.

Methods

void GetFontMetrics(const kFont &font, kFontMetrics &metrics)

Retrieve font metrics.
font - font resource object.
metrics - kFontMetrics structure which will receive metrics data.

void GetGlyphMetrics(
    const kFont &font, size_t first, size_t last,
    kGlyphMetrics *metrics
)

Retrieve individual glyphs metrics.
font - font resource object.
first - first glyph code in range.
last - last glyph code in range (inclusive).
metrics - pointer to array of kGlyphMetrics structures.
Array pointed to by metrics should at least have space for (last - first) + 1 structures.

kSize TextSize(
    const char *text, int count, const kFont &font,
    const kTextSizeProperties *properties, kRect *bounds
)

Measure string of text.
text - pointer to text string.
count - number of bytes in a string, set to -1 if text string is null terminated string.
font - font resource object.
properties - optional text properties structure with additional measurement properties.
bounds - optional rectangle which receives calculated text bounds.
Returns size of measured text with respect to given properties.
If properties is not passed text is measured as single line text with 0 identation and line breaks ignore.

Examples

kTextService usage shown in text and fonts example.

kCanvas

class kCanvas : public kTextService
{
public:
    void Line(const kPoint &a, const kPoint &b, const kPen &pen);

    void Bezier(
        const kPoint &p1, const kPoint &p2,
        const kPoint &p3, const kPoint &p4, const kPen &pen
    );

    void Arc(const kRect &rect, kScalar start, kScalar end, const kPen &pen);
    void PolyLine(const kPoint *points, size_t count, const kPen &pen);
    void PolyBezier(const kPoint *points, size_t count, const kPen &pen);

    void Rectangle(const kRect &rect, const kPen *pen, const kBrush *brush);

    void RoundedRectangle(
        const kRect &rect, const kSize &round,
        const kPen *pen, const kBrush *brush
    );

    void Ellipse(const kRect &rect, const kPen *pen, const kBrush *brush);

    void Polygon(
        const kPoint *points, size_t count,
        const kPen *pen, const kBrush *brush
    );

    void PolygonBezier(
        const kPoint *points, size_t count,
        const kPen *pen, const kBrush *brush
    );

    void DrawPath(const kPath &path, const kPen *pen, const kBrush *brush);

    void DrawPath(
        const kPath &path, const kPen *pen, const kBrush *brush,
        const kPoint &offset
    );

    void DrawPath(
        const kPath &path, const kPen *pen, const kBrush *brush,
        const kTransform &transform
    );

    void DrawBitmap(
        const kBitmap &bitmap, const kPoint &origin,
        kScalar sourcealpha = 1.0f
    );

    void DrawBitmap(
        const kBitmap &bitmap, const kPoint &origin, const kPoint &source,
        const kSize &size, kScalar sourcealpha = 1.0f
    );

    void DrawBitmap(
        const kBitmap &bitmap, const kPoint &origin, const kSize &destsize,
        const kPoint &source, const kSize &sourcesize, kScalar sourcealpha = 1.0f
    );

    void DrawMask(const kBitmap &mask, kBrush &brush, const kPoint &origin);

    void DrawMask(
        const kBitmap &mask, kBrush &brush, const kPoint &origin,
        const kPoint &source, const kSize &size
    );

    void DrawMask(
        const kBitmap &mask, kBrush &brush, const kPoint &origin, const kSize &destsize,
        const kPoint &source, const kSize &sourcesize
    );

    void Text(
        const kPoint &p, const char *text, int count, const kFont &font,
        const kBrush &brush, kTextOrigin origin = kTextOrigin::Top
    );

    void Text(
        const kRect &rect, const char *text, int count, const kFont &font,
        const kBrush &brush, const kTextOutProperties *properties = nullptr
    );

    void SetTransform(const kTransform &transform);
    void PushTransform(const kTransform &transform);
    void PopTransform();

    static bool Initialize(Impl implementation = IMPL_NONE);
    static bool Shutdown();

protected:
    kCanvas();
    ~kCanvas();
};

kCanvas class defines general canvas API functionality. Object of this class can not be instantiated directly - use one of specific kBitmapCanvas or kContextCanvas to construct canvas instance. Any specific instance of canvas object can be passed around as a kCanvas object (by pointer or reference).

State

There's some state tied to canvas object: stack and transformation stack. All painting operations are affected by current transformation state. There's also implicit state which is controlled by other API classes and from user's point of view it's not reflected as a canvas object's state by itself.

Overview

There are several groups of functions: line drawing, filled shapes drawing, bitmap and mask drawing, text drawing, transformation stack control.

Line drawing functions always take a kPen object which defines properties for line drawing. This is mandatory parameter. Filled shapes drawing functions always take kPen and kBrush objects which define properties for shape outline painting and interior filling. This parameters are both optional and if both of them are null nothing will be painted.

Methods

Group of line drawing functions presented next. Sample usage of these functions is shown in basic shapes example.

void Line(const kPoint &a, const kPoint &b, const kPen &pen)

Draw straight line.
a - line starting point.
b - line ending point.
pen - pen resource object.

void Bezier(
    const kPoint &p1, const kPoint &p2,
    const kPoint &p3, const kPoint &p4, const kPen &pen
)

Draw cubic bezier line segment.
p1 - line starting point.
p2 - first control point.
p3 - second control point.
p4 - line ending point.
pen - pen resource object.

void Arc(const kRect &rect, kScalar start, kScalar end, const kPen &pen)

Draw arc segment.
rect - bounding rect for arc ellipse.
start - arc starting angle in degrees.
end - arc ending angle in degrees.
pen - pen resource object.

void PolyLine(const kPoint *points, size_t count, const kPen &pen)

Draw multiple straight line segments connected together.
points - pointer to kPoint array.
count - number of points in the points array.
pen - pen resource object.
Minimum allowed point count is 2.

void PolyBezier(const kPoint *points, size_t count, const kPen &pen)

Draw multiple bezier line segments connected together.
points - pointer to kPoint array.
count - number of points in the points array.
pen - pen resource object.
Minimum allowed point count is 4. First 4 points define first bezier segment, every next 3 points define next bezier segments where previous segment ending point treated as starting point for next segment.

Group of filled shapes drawing functions presented next. Sample usage of these functions is shown in basic filled shapes example. kPath object is a shape definition object, its usage shown in paths example.

void Rectangle(const kRect &rect, const kPen *pen, const kBrush *brush)

Draw filled rectangle.
rect - rectangle to draw.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.

void RoundedRectangle(
    const kRect &rect, const kSize &round,
    const kPen *pen, const kBrush *brush
)

Draw filled rectangle with round corners.
rect - rectangle to draw.
round - X and Y radius for corner rounding.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.

void Ellipse(const kRect &rect, const kPen *pen, const kBrush *brush)

Draw filled ellipse.
rect - ellipse boudning rectangle.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.

void Polygon(
    const kPoint *points, size_t count,
    const kPen *pen, const kBrush *brush
)

Draw filled polygon formed by straight line segments.
points - pointer to kPoint array.
count - number of points in the points array.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.
Minimum allowed point count is 3. Last polygon point is always automatically connected to first with a straight line segment. Polygon shape is always closed.

void PolygonBezier(
    const kPoint *points, size_t count,
    const kPen *pen, const kBrush *brush
)

Draw filled polygon formed by bezier line segments.
points - pointer to kPoint array.
count - number of points in the points array.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.
Minimum allowed point count is 6. First polygon segment is formed by first 4 points, every next segment is formed by 3 points. Last polygon segment is formed only by 2 points (which are control points), previous segment ending point and very first point become segment boundary points.

void DrawPath(const kPath &path, const kPen *pen, const kBrush *brush)

Draw shape defined by kPath object.
path - path object.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.

void DrawPath(
    const kPath &path, const kPen *pen, const kBrush *brush,
    const kPoint &offset
)

Draw shape defined by path with offset applied.
path - path object.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.
offset - offset for X and Y axes.

void DrawPath(
    const kPath &path, const kPen *pen, const kBrush *brush,
    const kTransform &transform
)

Draw shape defined by path with arbitrary transformation applied.
path - path object.
pen - optional pen resource object for outline drawing.
brush - optional brush resource object for filling.
transform - transform which will be applied to path shape while drawing.
Transform passed to this function is not the same as applying global transformation. Global transformation affects everything (line width, fill pattern scaling), transform passed here affects only path shape.

Group of bitmap and mask drawing functions presented next. Sample usage of these functions shown in bitmaps example.

void DrawBitmap(
    const kBitmap &bitmap, const kPoint &origin,
    kScalar sourcealpha
)

Draw bitmap at specified origin with its original size.
bitmap - bitmap object to be drawn.
origin - location of top-left corner of a bitmap.
sourcealpha - global transparency value for whole bitmap. Modulated with original bitmap's alpha channel.

void DrawBitmap(
    const kBitmap &bitmap, const kPoint &origin, const kPoint &source,
    const kSize &size, kScalar sourcealpha
)

Draw part of a bitmap with original scale.
bitmap - bitmap object to be drawn.
origin - destination location of top-left corner of a bitmap part.
source - source location of top-left corner of a bitmap part.
size - bitmap part size.
sourcealpha - global transparency value for whole bitmap. Modulated with original bitmap's alpha channel.

void DrawBitmap(
    const kBitmap &bitmap, const kPoint &origin, const kSize &destsize,
    const kPoint &source, const kSize &sourcesize, kScalar sourcealpha
)

Draw part of a bitmap with rescaling to required size.
bitmap - bitmap object to be drawn.
origin - destination location of top-left corner of a bitmap part.
destsize - resulting size of a bitmap part.
source - source location of top-left corner of a bitmap part.
sourcesize - bitmap part size (in original bitmap coordinate space).
sourcealpha - global transparency value for whole bitmap. Modulated with original bitmap's alpha channel.

void DrawMask(const kBitmap &mask, kBrush &brush, const kPoint &origin)

Fill mask bitmap with specified brush and its original size.
mask - mask bitmap, should be in kBitmapFormat::Mask8Bit format.
brush - brush object for filling.
origin - location of top-left corner of a mask.

void DrawMask(
    const kBitmap &mask, kBrush &brush, const kPoint &origin,
    const kPoint &source, const kSize &size
)

Fill part of mask bitmap with specified brush and its original scale.
mask - mask bitmap, should be in kBitmapFormat::Mask8Bit format.
brush - brush object for filling.
origin - destination location of top-left corner of a mask.
source - source location of top-left corner of a mask part.
size - mask part size.

void DrawMask(
    const kBitmap &mask, kBrush &brush, const kPoint &origin, const kSize &destsize,
    const kPoint &source, const kSize &sourcesize
)

Fill part of a mask with specified brush and rescaling to required size.
mask - mask bitmap, should be in kBitmapFormat::Mask8Bit format.
brush - brush object for filling.
origin - destination location of top-left corner of a mask part.
destsize - resulting size of a mask part.
source - source location of top-left corner of a mask part.
sourcesize - mask part size (in original mask bitmap coordinate space).

Group of text drawing functions presented next. Example of their usage can be seen in text and fonts example.

void Text(
    const kPoint &p, const char *text, int count, const kFont &font,
    const kBrush &brush, kTextOrigin origin
)

Draw single line of text at given origin.
p - text origin.
text - pointer to text string.
count - number of bytes in a string, set to -1 if text string is null terminated string.
font - font resource object.
brush - brush resource object.
origin - text position relative to origin point.

void Text(
    const kRect &rect, const char *text, int count, const kFont &font,
    const kBrush &brush, const kTextOutProperties *properties
)

Draw single- or multiline text within specified rectangle with optional layout and word wrapping.
rect - text bounding rectangle.
text - pointer to text string.
count - number of bytes in a string, set to -1 if text string is null terminated string.
font - font resource object.
brush - brush resource object.
properties - optional text drawing properties structure.

Group of global transformation state manipulation functions presented next.

void SetTransform(const kTransform &transform)

Set current transform (at the top of the stack).

void PushTransform(const kTransform &transform)

Push new transform at the top of the stack. Previously set of transforms remains active.

void PopTransform()

Pop last pushed tranform from the stack.

kCanvasClipper

class kCanvasClipper
{
public:
    kCanvasClipper(
        kCanvas &canvas, const kBitmap &mask,
        const kTransform &transform = kTransform(),
        kExtendType xextend = kExtendType::Clamp,
        kExtendType yextend = kExtendType::Clamp
    );
    kCanvasClipper(
        kCanvas &canvas, const kPath &clip,
        const kTransform &transform = kTransform()
    );
    kCanvasClipper(kCanvas &canvas, const kRect &clip);
    ~kCanvasClipper();

private:
    kCanvasClipper(const kCanvasClipper &source);
    kCanvasClipper& operator=(const kCanvasClipper &source);
};

This helper class explicitly controls clipping and masking state of canvas object.

Methods

void kCanvasClipper(
    kCanvas &canvas, const kBitmap &mask, const kTransform &transform,
    kExtendType xextend, kExtendType yextend
)

Construct new clipper object wich will restrict painting by provided mask. Clipping state restored back when clipper object gets destructed.
canvas - canvas object for which this clipping operation is applied.
mask - mask bitmap, should be in kBitmapFormat::Mask8Bit format.
tranform - mask bitmap transformation.
xextend - mask extend along X axis.
yextend - mask extend along Y axis.

void kCanvasClipper(kCanvas &canvas, const kPath &clip, const kTransform &transform)

Construct new clipper object which will restrict painting by provided kPath shape. Clipping state restored back when clipper object gets destructed.
canvas - canvas object for which this clipping operation is applied.
clip - kPath object which defines clipping shape.
transform - clipping shape transformation.

void kCanvasClipper(kCanvas &canvas, const kRect &clip)

Construct new clipper object which will restrict painting by provided rectangle. Clipping state restored back when clipper object gets destructed.
canvas - canvas object for which this clipping operation is applied.
clip - clipping rectangle.

void ~kCanvasClipper()

Destroys clipper object and restores clipping state.

Examples

Example for clipping and masking usage can be seen in clipping and masking example.

kBitmapCanvas

class kBitmapCanvas : public kCanvas
{
public:
    kBitmapCanvas(const kBitmap &target, const kRectInt *rect = nullptr);
    ~kBitmapCanvas();

private:
    kBitmapCanvas(const kBitmapCanvas &source);
    kBitmapCanvas& operator=(const kBitmapCanvas &source);
};

kBitmapCanvas directs all painting into specified kBitmap object.

Methods

kBitmapCanvas(const kBitmap &target, const kRectInt *rect)

Construct instance of canvas object with rendering directed to kBitmap object.
target - bitmap object which will receive painting.
rect - optional rectangle that defines painting area inside bitmap.
If rect specified it will be clipped against bitmap dimensions. All painting will be clipped to resulting rectangle. Use it to restrict painting to specific rectangle inside bitmap, rest of the bitmap image data will remain unchaged.

kContextCanvas

class kContextCanvas : public kCanvas
{
public:
    kContextCanvas(kContext context, const kRectInt *rect = nullptr);
    ~kContextCanvas();

private:
    kContextCanvas(const kContextCanvas &source);
    kContextCanvas& operator=(const kContextCanvas &source);
};

kContextCanvas directs all painting to specific platform dependent context (typically tied to application window). kContext has specific meaning to specific implementation (for example, on Windows platform it's equivalent to HDC).

Methods

kContextCanvas(kContext context, const kRectInt *rect)

Construct instance of canvas object with rendering directed to specified context.
context - implementation specific context which will receive painting.
rect - optional rectangle that defines painting area inside context area.
If rect specified it will be clipped against context area available for painting (if any). All painting will be clipped to resulting rectangle. Use it to restrict painting to specific rectangle inside context area.