DOCSEARCHbyAlgolia
Submit Docs

SkiaSharp.Extended

repository·main·Indexed 42 days ago

https://github.com/mono/skiasharp.extended

A collection of libraries providing additional APIs and .NET MAUI controls built on top of the SkiaSharp graphics engine. It includes utilities for Blur Hash image placeholders, geometric shape generation via SKGeometry, and specialized UI components like SKConfettiView and SKLottieView for .NET MAUI applications.

Tokens
10.4K
Snippets
34
Records
46
Agent score
52%

What's inside SkiaSharp.Extended

  1. Overview of SkiaSharp.Extended.UI.Maui Controls

    main

    The MAUI-specific package provides high-level controls for rich visual effects:

    • Lottie Animations: A control to play designer-created After Effects animations exported as Lottie JSON files.
    • Confetti Effects: A control to trigger customizable particle explosions for celebratory UI moments.

  3. Overview of SkiaSharp.Extended Core Utilities

    main

    The core library provides several specialized graphics utilities:

    • Blur Hash: Generates compact placeholder representations of images to show beautiful blurs while full images load.
    • Geometry Helpers: Provides simple methods to create regular polygons, stars, and other geometric shapes.
    • Path Interpolation: Enables smooth morphing between two different paths, useful for shape transitions and animations.
    • Pixel Comparer: Allows for pixel-by-pixel image comparison, quantifying differences and generating visual masks, which is ideal for visual regression testing.

  4. Explore SkiaSharp.Extended core features

    main

    The core SkiaSharp.Extended library provides several specialized graphics utilities:

    • Blur Hash: Encode and decode compact image placeholders using the BlurHash algorithm.
    • Geometry Helpers: Generate SKPath objects for regular polygons, stars, and other complex shapes.
    • Path Interpolation: Perform smooth morphing/transitions between two SKPath objects.
    • Pixel Comparer: Perform pixel-by-pixel image comparison, quantify differences, and generate visual difference masks (useful for regression testing).

  5. Explore SkiaSharp.Extended.UI.Maui features

    main

    The SkiaSharp.Extended.UI.Maui package provides ready-to-use .NET MAUI controls:

    • Lottie Animations: Play After Effects animations (exported as Lottie JSON) using the SKLottieView control.
    • Confetti Effects: Trigger customizable particle explosions with specific shapes, colors, and physics using the SKConfettiView control.

  7. Control path winding order with SKPathDirection

    main

    All shape creation methods in SKGeometry accept an optional SKPathDirection parameter. This allows you to control the winding order of the path, which is useful when performing path operations like creating holes or combining multiple paths.

    • SKPathDirection.Clockwise (Default)
    • SKPathDirection.CounterClockwise
    // Clockwise (default)
var cwPath = SKGeometry.CreateSquarePath(50, SKPathDirection.Clockwise);

// Counter-clockwise
var ccwPath = SKGeometry.CreateSquarePath(50, SKPathDirection.CounterClockwise);

  8. Control Lottie playback and repeat modes

    main

    Configure how an animation repeats using the RepeatCount and RepeatMode properties:

    RepeatCount

    • 0: Play once and stop.
    • n (positive integer): Repeat exactly n times.
    • -1: Loop forever.

    RepeatMode

    • Restart (default): Starts from the beginning after each loop.
    • Reverse: Plays forward, then backward (ping-pong effect). Use this in conjunction with RepeatCount="-1" for continuous ping-ponging.
    <!-- Play once and stop -->
<skia:SKLottieView Source="animation.json" RepeatCount="0" />

<!-- Repeat 3 times -->
<skia:SKLottieView Source="animation.json" RepeatCount="3" />

<!-- Loop forever -->
<skia:SKLottieView Source="animation.json" RepeatCount="-1" />

<!-- Ping-pong (play forward, then backward) -->
<skia:SKLottieView Source="animation.json" RepeatCount="-1" RepeatMode="Reverse" />

  9. Perform tolerance-based comparison

    main

    You can specify a uniform per-pixel tolerance threshold to ignore minor differences.

    Per-Channel Mode (Default)

    Each channel (R, G, B) is checked independently. If a channel's difference is within the tolerance, it is ignored. If a pixel falls within tolerance for all channels, it is excluded from all metrics (including ErrorPixelCount, AbsoluteError, etc.).

    Summed Mode

    By setting TolerancePerChannel = false in SKPixelComparerOptions, the total difference (|ΔR| + |ΔG| + |ΔB|) is compared against the tolerance. In this mode, the entire pixel is either counted as an error or excluded entirely.

    Note: A negative tolerance throws ArgumentOutOfRangeException.

    // Per-channel tolerance (default)
var result = SKPixelComparer.Compare(expected, actual, tolerance: 10);

// Summed tolerance mode
var options = new SKPixelComparerOptions { TolerancePerChannel = false };
var resultSummed = SKPixelComparer.Compare(expected, actual, tolerance: 15, options);

  10. Perform mask-based comparison

    main

    To ignore expected minor differences (like anti-aliasing or compression artifacts), you can provide a tolerance mask. Each channel's difference is checked independently against the corresponding channel value in the mask. The mask must have the same dimensions as the images being compared.

    using var expected = SKImage.FromEncodedData("expected.png");
using var actual = SKImage.FromEncodedData("actual.png");
using var mask = SKImage.FromEncodedData("tolerance-mask.png");

var result = SKPixelComparer.Compare(expected, actual, mask);

  11. Configure Emission Patterns and Bounds

    main

    The Emitter property defines the timing and quantity of particles, while EmitterBounds defines the spatial origin of the particles.

    Emitter Patterns

    • SKConfettiEmitter.Burst(count): Instant explosion where all particles appear at once.
    • SKConfettiEmitter.Stream(countPerSecond, duration): Continuous stream for a set period.
    • SKConfettiEmitter.Infinite(countPerSecond): Continuous stream that never ends.

    Emitter Bounds

    • SKConfettiEmitterBounds.Center: Particles appear from the center of the view.
    • SKConfettiEmitterBounds.Top: Particles appear from the top edge (falling down).
    • SKConfettiEmitterBounds.Left / SKConfettiEmitterBounds.Right: Particles appear from the sides.
    • SKConfettiEmitterBounds.Point(x, y): Particles appear from a specific coordinate.
    // Instant explosion
Emitter = SKConfettiEmitter.Burst(100);

// Continuous stream - 50 particles per second, for 3 seconds
Emitter = SKConfettiEmitter.Stream(50, 3);

// Infinite - 30 particles per second, forever
Emitter = SKConfettiEmitter.Infinite(30);

// From the top edge
EmitterBounds = SKConfettiEmitterBounds.Top;

// From a specific point
EmitterBounds = SKConfettiEmitterBounds.Point(100, 200);

  12. Understand the SkiaSharp.Extended library structure

    main

    SkiaSharp.Extended is split into two primary packages depending on your target environment:

    1. SkiaSharp.Extended: The core utility library. It provides image processing, geometry, and path manipulation tools. It targets netstandard2.0 and net10.0+.
    2. SkiaSharp.Extended.UI.Maui: A specialized package for .NET MAUI applications. It provides high-level UI controls for Lottie animations, confetti effects, and animated surface views across iOS, Android, macOS Catalyst, and Windows.