Canvas

by BlazorExtensions

BlazorExtensions / Canvas

HTML5 Canvas API implementation for Microsoft Blazor

263 Stars 69 Forks Last release: 12 months ago (v1.1.0-preview1) MIT License 57 Commits 7 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Canvas

HTML5 Canvas API implementation for Microsoft Blazor

Build Package Version NuGet Downloads License

Blazor Extensions

Blazor Extensions are a set of packages with the goal of adding useful things to Blazor.

Blazor Extensions Canvas

This package wraps HTML5 Canvas APIs.

Both Canvas 2D and WebGL are supported.

Both Blazor Server Apps and Blazor WebAssembly Apps are supported.

NOTE Currently targets the v3.0.0-preview8 version of Blazor.

Installation

Install-Package Blazor.Extensions.Canvas

Sample

Usage

In your

index.html
file (WebAssembly Apps) or
_Host.cshtml
(Server Apps) file, place a reference to the library's script file:

In your

_Imports.razor
add the following
using
entry:
@using Blazor.Extensions.Canvas

In the component where you want to place a canvas element, add a

BECanvas
. Make sure to set the
ref
to a field on your component:

2D

In your component C# code (regardless if inline on .razor or in a .cs file), add a

BECanvasComponent
reference which matches the
ref
you set on your
BECanvas
.

Create a

Canvas2DContext
, and then use the context methods to draw on the canvas:
private Canvas2DContext _context;

protected BECanvasComponent _canvasReference;

protected override async Task OnAfterRenderAsync(bool firstRender) { this._context = await this._canvasReference.CreateCanvas2DAsync(); await this._context.SetFillStyleAsync("green");

await this._context.FillRectAsync(10, 100, 100, 100);

await this._context.SetFontAsync("48px serif");
await this._context.StrokeTextAsync("Hello Blazor!!!", 10, 100);

}

NOTE You cannot call

CreateCanvas2DAsync
in
OnInitAsync
, because the underlying
 element is not yet present in the generated markup.

WebGL

In your component C# code (regardless if inline on .razor or in a .cs file), add a

BECanvasComponent
reference which matches the
ref
you set on your
BECanvas
.

Create a

WebGLContext
, and then use the context methods to draw on the canvas:
private WebGLContext _context;

protected BECanvasComponent _canvasReference;

protected override async Task OnAfterRenderAsync(bool firstRender) { this._context = await this._canvasReference.CreateWebGLAsync();

await this._context.ClearColorAsync(0, 0, 0, 1);
await this._context.ClearAsync(BufferBits.COLOR_BUFFER_BIT);

}

NOTE You cannot call

CreateWebGLAsync
in
OnInitAsync
, because the underlying
 element is not yet present in the generated markup.

Call Batching

All javascript interop are batched as needed to improve performance. In high-performance scenarios this behavior will not have any effect: each call will execute immediately. In low-performance scenarios, consective calls to canvas APIs will be queued. JavaScript interop calls will be made with each batch of queued commands sequentially, to avoid the performance impact of multiple concurrent interop calls.

When using server-side Razor Components, because of the server-side rendering mechanism, only the last drawing operation executed will appear to render on the client, overwriting all previous operations. In the example code above, for example, drawing the triangles would appear to "erase" the black background drawn immediately before, leaving the canvas transparent.

To avoid this issue, all WebGL drawing operations should be explicitly preceded and followed by

BeginBatchAsync
and
EndBatchAsync
calls.

For example:

await this._context.ClearColorAsync(0, 0, 0, 1); // this call does not draw anything, so it does not need to be included in the explicit batch

await this._context.BeginBatchAsync(); // begin the explicit batch

await this._context.ClearAsync(BufferBits.COLOR_BUFFER_BIT); await this._context.DrawArraysAsync(Primitive.TRIANGLES, 0, 3);

await this._context.EndBatchAsync(); // execute all currently batched calls

It is best to structure your code so that

BeginBatchAsync
and
EndBatchAsync
surround as few calls as possible. That will allow the automatic batching behavior to send calls in the most efficient manner possible, and avoid unnecessary performance impacts.

Methods which return values are never batched. Such methods may be called at any time, even after calling

BeginBatchAsync
, without interrupting the batching of other calls.

NOTE The "overwriting" behavior of server-side code is unpredictable, and shouldn't be relied on as a feature. In low-performance situations calls can be batched automatically, even when you don't explicitly use

BeginBatchAsync
and
EndBatchAsync
.

Contributions and feedback

Please feel free to use the component, open issues, fix bugs or provide feedback.

Contributors

The following people are the maintainers of the Blazor Extensions projects:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.