Mono Skiasharp Add API

Add API Skill

⚠️ Branch Protection (COMPLIANCE REQUIRED)

🛑 NEVER commit directly to protected branches. This is a policy violation.

BEFORE making any changes, create feature branches in BOTH repos:

# Step 1: Create branch in SkiaSharp repo
git checkout -b dev/issue-NNNN-description

# Step 2: Create branch in submodule (REQUIRED for C API changes)
cd externals/skia
git checkout -b dev/issue-NNNN-description
cd ../..

❌ NEVER Do These

Workflow Overview

1. Analyze C++ API  →  Find in Skia headers, identify pointer type
2. Add C API        →  Header + impl in externals/skia/
3. Commit Submodule →  Commit IN submodule, then stage in parent
4. Generate         →  Run pwsh ./utils/generate.ps1 (MANDATORY)
5. Add C# Wrapper   →  Validate params, call P/Invoke
6. Build Native     →  dotnet cake --target=externals-{platform} (MANDATORY)
7. Test             →  Run tests — must PASS (MANDATORY)

👉 Detailed checklists: references/checklists.md 👉 Troubleshooting: references/troubleshooting.md

Phase 1: Analyze C++ API

Find the C++ API in Skia headers and identify:

1. Pointer type — determines C# wrapper pattern:

   • Raw (T*) → owns: false
   • Owned → DisposeNative() deletes
   • Ref-counted (sk_sp<T>) → ISKReferenceCounted or ISKNonVirtualReferenceCounted

2. Error handling — returns null/bool? throws?

3. Parameters — primitives, references, pointers, const-ness

👉 See ../../../documentation/dev/memory-management.md#pointer-type-decision-tree

Phase 2: Add C API

Location: externals/skia/include/c/ (header) and externals/skia/src/c/ (impl)

// Header (sk_canvas.h)
SK_C_API void sk_canvas_draw_circle(sk_canvas_t* canvas, float cx, float cy, 
                                     float radius, const sk_paint_t* paint);

// Implementation (sk_canvas.cpp)
void sk_canvas_draw_circle(sk_canvas_t* canvas, float cx, float cy,
                           float radius, const sk_paint_t* paint) {
    AsCanvas(canvas)->drawCircle(cx, cy, radius, *AsPaint(paint));
}

Conversion macros: AsType() unwraps, ToType() wraps. Use sk_ref_sp() for ref-counted params, .release() for ref-counted returns.

Phase 3: Commit Submodule

🛑 CRITICAL — This is where changes get lost

# Step 1: Commit IN the submodule
cd externals/skia
git config user.email "you@example.com"  # first time only
git config user.name "Your Name"             # first time only
git add include/c/sk_*.h src/c/sk_*.cpp
git commit -m "Add sk_foo_bar to C API"

# Step 2: Stage submodule in parent
cd ../..  # Back to repo root
git add externals/skia

# Step 3: Verify
git status
# Must show: modified: externals/skia (new commits)

Phase 4: Generate Bindings

🛑 MANDATORY — Never skip, never edit generated files manually

pwsh ./utils/generate.ps1
git diff binding/SkiaSharp/SkiaApi.generated.cs  # verify new function appears

Phase 5: Add C# Wrapper

Location: binding/SkiaSharp/SK*.cs

// Factory method — returns null on failure
public static SKImage FromPixels(SKImageInfo info, SKData data, int rowBytes)
{
    if (data == null)
        throw new ArgumentNullException(nameof(data));
    var cinfo = SKImageInfoNative.FromManaged(ref info);
    return GetObject(SkiaApi.sk_image_new_raster_data(&cinfo, data.Handle, (IntPtr)rowBytes));
}

// Instance method
public void DrawCircle(float cx, float cy, float radius, SKPaint paint)
{
    if (paint == null)
        throw new ArgumentNullException(nameof(paint));
    SkiaApi.sk_canvas_draw_circle(Handle, cx, cy, radius, paint.Handle);
}

Rules: Validate nulls, factory→null on fail, constructor→throw on fail, use overloads not defaults (ABI stability).

Phase 6: Build & Test

🛑 MANDATORY — You modified the C API, so you MUST build the native library

Step 1: Build Native Library (REQUIRED)

Since you added/modified C API functions in Phase 2, you MUST rebuild the native library before testing. The pre-built natives from externals-download do not contain your new functions.

# macOS (Apple Silicon)
dotnet cake --target=externals-macos --arch=arm64

# macOS (Intel)
dotnet cake --target=externals-macos --arch=x64

# Windows (x64)
dotnet cake --target=externals-windows --arch=x64

# Linux (requires Docker)
dotnet cake --target=externals-linux --arch=x64

⚠️ Native builds take 10-30 minutes. Only build for platforms you can test on.

Step 2: Write Tests

[SkippableFact]
public void DrawCircleWorks()
{
    using var surface = SKSurface.Create(new SKImageInfo(100, 100));
    using var canvas = surface.Canvas;
    using var paint = new SKPaint { Color = SKColors.Red };
    
    canvas.DrawCircle(50, 50, 25, paint);
    
    using var image = surface.Snapshot();
    Assert.NotNull(image);
}

Step 3: Run Tests

dotnet build binding/SkiaSharp/SkiaSharp.csproj
dotnet test tests/SkiaSharp.Tests.Console.sln

🛑 Tests MUST PASS. Do not skip tests. Do not claim completion if tests fail.

Skipping tests is only acceptable for hardware limitations (no GPU, no screen attached). EntryPointNotFoundException means you forgot to build the native library — go back to Step 1.

Tests must pass before claiming completion.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.