Using dplug canvas or canvasity

Using dplug:canvas or canvasity

Here is a tutorial for using:

• Either the dplug:canvaspackage,
• Or the canvasity package (code).

You will probably end-up using both, depending on the situation.

1. Adding as dependency

In your dub.json/dub.sdl, add either dplug:canvas or canvasity as dependency.

2. Importing

• For canvasity:

  import gamut;
  import canvasity;

• For dplug:canvas:

  import dplug.canvas;

3. Widget member

• For canvasity:

  private:
      Canvasity canvas;

• For dplug:canvas:

  private:
      Canvas canvas;

4. Drawing

• For canvasity:

  override void onDrawRaw(ImageRef!RGBA rawMap, box2i[] dirtyRects)
  {
      foreach(dirtyRect; dirtyRects)
      {
          auto cRaw = rawMap.cropImageRef(dirtyRect);
          Image img;
          createViewFromImageRef(img, cRaw);
          canvas.initialize(img);
          canvas.translate(-dirtyRect.min.x, -dirtyRect.min.y);
  
          // ...Draw...
     }
  }

  Canvasity works on any gamut image, while dplug:canvas works on ImageRef.

• For dplug:canvas:

  override void onDrawRaw(ImageRef!RGBA rawMap, box2i[] dirtyRects)
  {
      foreach(dirtyRect; dirtyRects)
      {
          auto cRaw = rawMap.cropImageRef(dirtyRect);
          canvas.initialize(cRaw);
          canvas.translate(-dirtyRect.min.x, -dirtyRect.min.y);
  
          // ...Draw...
     }
  }

Now is the best part: both can be used at once on the same buffer.

5. Features

Feature	dplug:canvas	canvasity
Identifier	Canvas	Canvasity
Licence	BSL-1.0	ISC
Speed	✅	❌
Fully debugged	✅	❌
Backing format	ImageRef!RGBA	Any Gamut Image
nothrow @nogc	✅	✅
Amortized allocations	✅	✅
No exceptions	✅	✅
.beginPath()	✅	✅
.closePath()	✅	✅
.moveTo()	✅	✅
.lineTo()	✅	✅
.bezierCurveTo()	✅	✅
.quadraticCurveTo()	✅	✅
.arc()	✅	✅
.rect()	✅	✅
.arcTo()	✅	✅
.rotate()	✅	✅
.scale()	✅	✅
.fill()	✅	✅
.clearRect()	❌	✅
.fillRect()	✅	✅
.fillStyle	✅	✅
.fillText	❌	❌
.fillRule	✅	❌
.stroke()	❌	✅
.strokeStyle	❌	✅
.strokeText	❌	❌
.lineJoin	❌	✅
.lineCap	❌	✅
Trapezoidal AA	❌	✅
Gradient support	✅	❌ (FUTURE)
Gamma-aware	❌	✅ (brightness of result could differ a lot)
CSS colors	✅	✅
string constants	Partial	✅
.shadowBlur	❌	✅
.setLineDash	❌	✅
.lineWidth	❌	✅
.clip	❌	✅
.globalAlpha	❌	✅
.globalCompositeOperation	source-over add lighter subtract lighten darken	source-in copy source-out destination-in destination-atop add lighter destination-over destination-out source-atop source-over xor
.save	✅	✅
.restore	✅	✅

6. Best possible quality with canvasity, outside of Dplug

If you're using canvasity outside of Dplug context, here is how to get the absolute best visual quality:

• use a PixelType.rgbaf32 backing buffer
• Use the CanvasOptions and choose the best quality options
• add dithering to output when converting back to 8-bit, see original canvas_ity.h