Repository files navigation

HTML5 Canvas API implementation for Microsoft Blazor

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

This package wrapsHTML5 Canvas APIs.

Both Canvas 2D and WebGL are supported.

Both Blazor Server Apps and Blazor WebAssembly Apps are supported.

NOTE Currently targets the v3.1.5 of Blazor with 3.2.0 of WebAssembly

Install-Package Blazor.Extensions.Canvas

In yourindex.html file (WebAssembly Apps) or_Host.cshtml (Server Apps) file, place a reference to the library's script file:

<scriptsrc="_content/Blazor.Extensions.Canvas/blazor.extensions.canvas.js"></script>

In your_Imports.razor add the followingusing entry:

@usingBlazor.Extensions.Canvas

In the component where you want to place a canvas element, add aBECanvas. Make sure to set theref to a field on your component:

<BECanvasWidth="300"Height="400"@ref="_canvasReference"></BECanvas>

In your component C# code (regardless if inline on .razor or in a .cs file), add aBECanvasComponent reference which matches theref you set on yourBECanvas.

Create aCanvas2DContext, and then use the context methods to draw on the canvas:

privateCanvas2DContext_context;protectedBECanvasComponent_canvasReference;protectedoverrideasyncTaskOnAfterRenderAsync(boolfirstRender){this._context=awaitthis._canvasReference.CreateCanvas2DAsync();awaitthis._context.SetFillStyleAsync("green");awaitthis._context.FillRectAsync(10,100,100,100);awaitthis._context.SetFontAsync("48px serif");awaitthis._context.StrokeTextAsync("Hello Blazor!!!",10,100);}

NOTE You cannot callCreateCanvas2DAsync inOnInitAsync, because the underlying<canvas> element is not yet present in the generated markup.

In your component C# code (regardless if inline on .razor or in a .cs file), add aBECanvasComponent reference which matches theref you set on yourBECanvas.

Create aWebGLContext, and then use the context methods to draw on the canvas:

privateWebGLContext_context;protectedBECanvasComponent_canvasReference;protectedoverrideasyncTaskOnAfterRenderAsync(boolfirstRender){this._context=awaitthis._canvasReference.CreateWebGLAsync();awaitthis._context.ClearColorAsync(0,0,0,1);awaitthis._context.ClearAsync(BufferBits.COLOR_BUFFER_BIT);}

NOTE You cannot callCreateWebGLAsync inOnInitAsync, because the underlying<canvas> element is not yet present in the generated markup.

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 WebGLdrawing operations should be explicitly preceded and followed byBeginBatchAsync andEndBatchAsync calls.

For example:

awaitthis._context.ClearColorAsync(0,0,0,1);// this call does not draw anything, so it does not need to be included in the explicit batchawaitthis._context.BeginBatchAsync();// begin the explicit batchawaitthis._context.ClearAsync(BufferBits.COLOR_BUFFER_BIT);awaitthis._context.DrawArraysAsync(Primitive.TRIANGLES,0,3);awaitthis._context.EndBatchAsync();// execute all currently batched calls

It is best to structure your code so thatBeginBatchAsync andEndBatchAsync 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 callingBeginBatchAsync, 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 useBeginBatchAsync andEndBatchAsync.

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

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

• Attila Hajdrik
• Gutemberg Ribiero