BlockSuite

Appearance

BlockSuite API Documentation / @blocksuite/affine-gfx-turbo-renderer

@blocksuite/affine-gfx-turbo-renderer ​

Classes ​

Extension ​

abstract BlockLayoutHandlerExtension<T> ​

Understanding Extensions ​

Extensions provide a way to extend the functionality of a system using dependency injection. They allow you to register services, implementations, and factories in the DI container, which can then be retrieved and used by different parts of the application.

Extensions are particularly useful for:

  • Registering different implementations for different types
  • Creating pluggable architecture where components can be added or removed
  • Managing dependencies between different parts of the application

Usage Example: Fruit Processing System ​

Let's consider a fruit processing system where different types of fruits need different processing methods. We'll show how to implement this using extensions.

Step 1: Define the interfaces ​

ts
interface FruitProcessor {
  process(fruit: Fruit): void;
}

interface Fruit {
  type: string;
  // other properties
}

Step 2: Create a service identifier ​

ts
import { createIdentifier } from '@blocksuite/global/di';

const FruitProcessorProvider = createIdentifier<FruitProcessor>('fruit-processor-provider');

Step 3: Create implementations ​

ts
class AppleProcessor implements FruitProcessor {
  process(fruit: Fruit): void {
    console.log('Slicing apple');
    // Apple-specific processing
  }
}

class BananaProcessor implements FruitProcessor {
  process(fruit: Fruit): void {
    console.log('Peeling banana');
    // Banana-specific processing
  }
}

Step 4: Create an extension factory ​

ts
const FruitProcessorExtension = (
  fruitType: string,
  implementation: new () => FruitProcessor
): ExtensionType => {
  return {
    setup: di => {
      di.addImpl(FruitProcessorProvider(fruitType), implementation);
    }
  };
};

Step 5: Create concrete extensions ​

ts
export const AppleProcessorExtension = FruitProcessorExtension('apple', AppleProcessor);
export const BananaProcessorExtension = FruitProcessorExtension('banana', BananaProcessor);

Step 6: Use the extensions ​

ts
import { Container } from '@blocksuite/global/di';

class FruitProcessingSystem {
  provider: ServiceProvider;

  constructor(extensions: ExtensionType[]) {
    const container = new Container();

    // Set up all extensions
    extensions.forEach(ext => ext.setup(container));

    // Create a provider from the container
    this.provider = container.provider();
  }

  processFruit(fruit: Fruit) {
    // Get the appropriate processor based on fruit type
    const processor = this.provider.get(FruitProcessorProvider(fruit.type));

    // Process the fruit
    processor.process(fruit);
  }
}

// Initialize the system with extensions
const system = new FruitProcessingSystem([
  AppleProcessorExtension,
  BananaProcessorExtension
]);

// Use the system
system.processFruit({ type: 'apple' });  // Output: Slicing apple
system.processFruit({ type: 'banana' }); // Output: Peeling banana

Note: We deliberately used a non-block specific example here. In BlockSuite, the extension pattern can be applied to any entity that can be configured by third parties, not just blocks. This includes different tools in the whiteboard, different column types in database blocks, and many other extensible components. The pattern remains the same regardless of what you're extending.

Extends ​
Extended by ​
Type Parameters ​
T ​

T extends BlockLayout = BlockLayout

Constructors ​
Properties ​
blockType ​

abstract readonly blockType: string

Methods ​
calculateBound() ​

abstract calculateBound(layout): object

Parameters ​
layout ​

T

Returns ​

object

rect ​

rect: Rect

subRects ​

subRects: Rect[]

queryLayout() ​

abstract queryLayout(model, host, viewportRecord): T | null

Parameters ​
model ​

BlockModel

host ​

EditorHost

viewportRecord ​

ViewportRecord

Returns ​

T | null

Other ​

ViewportLayoutPainter ​

Constructors ​
Constructor ​

new ViewportLayoutPainter(extensions): ViewportLayoutPainter

Parameters ​
extensions ​

ExtensionType[]

Returns ​

ViewportLayoutPainter

Properties ​
provider ​

provider: ServiceProvider

Methods ​
getPainter() ​

getPainter(type): BlockLayoutPainter | null

Parameters ​
type ​

string

Returns ​

BlockLayoutPainter | null

handler() ​

handler(e): Promise<void>

Parameters ​
e ​

MessageEvent<MessagePaint>

Returns ​

Promise<void>

paint() ​

paint(layout, version): void

Parameters ​
layout ​

ViewportLayoutTree

version ​

number

Returns ​

void

paintTree() ​

paintTree(layout, version): void

Parameters ​
layout ​

ViewportLayoutTree

version ​

number

Returns ​

void

setSize() ​

setSize(layoutRectW, layoutRectH, dpr, zoom): void

Parameters ​
layoutRectW ​

number

layoutRectH ​

number

dpr ​

number

zoom ​

number

Returns ​

void

ViewportTurboRendererExtension ​

Manages the Turbo Rendering process for the viewport, coordinating between the main thread and a painter worker. Turbo Rendering optimizes performance by rendering block content onto a canvas bitmap, falling back to standard DOM rendering during interactions.

To add Turbo Rendering support for a new block type (e.g., 'affine:my-block'):

  1. In the block's package (e.g., blocksuite/affine/blocks/my-block): a. Add @blocksuite/affine/gfx/turbo-renderer as a dependency in package.json and create a src/turbo directory. b. Implement the Layout Handler (e.g., MyBlockLayoutHandlerExtension) and Painter Worker (e.g., MyBlockLayoutPainterExtension). Refer to ParagraphLayoutHandlerExtension and ParagraphLayoutPainterExtension in blocksuite/affine/blocks/block-paragraph for implementation examples. c. Export the Layout Handler and Painter Worker extensions from the block package's main src/index.ts by adding these two explicit export statements:
    typescript
    export * from './turbo/my-block-layout-handler';
export * from './turbo/my-block-painter.worker';

d. Add an export mapping for the painter worker in package.json under the exports field (e.g., "./turbo-painter": "./src/turbo/my-block-painter.worker.ts"). e. Add a TypeScript project reference to blocksuite/affine/gfx/turbo-renderer in tsconfig.json.

  1. In the application integration point (e.g., packages/frontend/core/src/blocksuite/extensions and blocksuite/integration-test/src/__tests__/utils/renderer-entry.ts): a. In turbo-renderer.ts (or the file setting up TurboRendererConfigFactory):

    • Import and add the new Layout Handler extension to the patchTurboRendererExtension array (or equivalent DI setup). See how ParagraphLayoutHandlerExtension is added as a reference. b. In turbo-painter.worker.ts (the painter worker entry point):
    • Import and add the new Painter Worker extension to the ViewportLayoutPainter constructor's extension array. See how ParagraphLayoutPainterExtension is added as a reference.

  2. Run yarn affine init from the workspace root to update generated configuration files (workspace.gen.ts) and the lockfile (yarn.lock).

Note: Always ensure the directory structure and export patterns match the paragraph block (blocksuite/affine/blocks/block-paragraph) for consistency.

Extends ​
Constructors ​
Constructor ​

new ViewportTurboRendererExtension(gfx): ViewportTurboRendererExtension

Parameters ​
gfx ​

GfxController

Returns ​

ViewportTurboRendererExtension

Overrides ​

GfxExtension.constructor

Properties ​
canvas ​

readonly canvas: HTMLCanvasElement

layoutCacheData ​

layoutCacheData: ViewportLayoutTree | null = null

optimizedBlockIds ​

optimizedBlockIds: string[] = []

state$ ​

readonly state$: BehaviorSubject<RenderingState>

key ​

static key: string = 'viewportTurboRenderer'

Overrides ​

GfxExtension.key

Accessors ​
currentState ​
Get Signature ​

get currentState(): RenderingState

Returns ​

RenderingState

layoutCache ​
Get Signature ​

get layoutCache(): ViewportLayoutTree

Returns ​

ViewportLayoutTree

options ​
Get Signature ​

get options(): RendererOptions

Returns ​

RendererOptions

selection ​
Get Signature ​

get selection(): GfxSelectionManager

Returns ​

GfxSelectionManager

viewport ​
Get Signature ​

get viewport(): Viewport

Returns ​

Viewport

Methods ​
canUseBitmapCache() ​

canUseBitmapCache(): boolean

Returns ​

boolean

invalidate() ​

invalidate(): void

Returns ​

void

mounted() ​

mounted(): void

Returns ​

void

Overrides ​

GfxExtension.mounted

refresh() ​

refresh(): Promise<void>

Returns ​

Promise<void>

unmounted() ​

unmounted(): void

Returns ​

void

Overrides ​

GfxExtension.unmounted

extendGfx() ​

static extendGfx(gfx): void

Parameters ​
gfx ​

GfxController

Returns ​

void

Overrides ​

GfxExtension.extendGfx

setup() ​

static setup(di): void

Parameters ​
di ​

Container

Returns ​

void

Overrides ​

GfxExtension.setup

Interfaces ​

BlockLayout ​

Extends ​

  • Record<string, unknown>

Extended by ​

Indexable ​

[key: string]: unknown

Properties ​

blockId ​

blockId: string

rect ​

rect: object

h ​

h: number

w ​

w: number

x ​

x: number

y ​

y: number

type ​

type: string

BlockLayoutPainter ​

Methods ​

paint() ​

paint(ctx, block, layoutBaseX, layoutBaseY): void

Parameters ​
ctx ​

OffscreenCanvasRenderingContext2D

block ​

BlockLayout

layoutBaseX ​

number

layoutBaseY ​

number

Returns ​

void

BlockLayoutTreeNode ​

Properties ​

blockId ​

blockId: string

children ​

children: BlockLayoutTreeNode[]

layout ​

layout: BlockLayout

type ​

type: string

Rect ​

Properties ​

h ​

h: number

w ​

w: number

x ​

x: number

y ​

y: number

RendererOptions ​

Properties ​

debounceTime ​

debounceTime: number

enableBitmapRendering? ​

optional enableBitmapRendering: boolean

zoomThreshold ​

zoomThreshold: number

TextRect ​

Properties ​

rect ​

rect: Rect

text ​

text: string

TurboRendererConfig ​

Properties ​

options? ​

optional options: Partial<RendererOptions>

painterWorkerEntry() ​

painterWorkerEntry: () => Worker

Returns ​

Worker

ViewportLayoutTree ​

Properties ​

overallRect ​

overallRect: object

h ​

h: number

w ​

w: number

x ​

x: number

y ​

y: number

roots ​

roots: BlockLayoutTreeNode[]

ViewportState ​

Properties ​

viewportX ​

viewportX: number

viewportY ​

viewportY: number

viewScale ​

viewScale: number

zoom ​

zoom: number

Type Aliases ​

HostToWorkerMessage ​

HostToWorkerMessage = MessagePaint

MessageBitmapPainted ​

MessageBitmapPainted = object

Properties ​

bitmap ​

bitmap: ImageBitmap

type ​

type: "bitmapPainted"

version ​

version: number

MessagePaint ​

MessagePaint = object

Properties ​

data ​

data: object

dpr ​

dpr: number

height ​

height: number

layout ​

layout: ViewportLayoutTree

version ​

version: number

width ​

width: number

zoom ​

zoom: number

type ​

type: "paintLayout"

MessagePaintError ​

MessagePaintError = object

Properties ​

blockType ​

blockType: string

error ​

error: string

type ​

type: "paintError"

RenderingState ​

RenderingState = "inactive" | "pending" | "zooming" | "rendering" | "ready"

Represents the rendering state of the ViewportTurboRenderer

  • inactive: Renderer is not active
  • pending: Bitmap is invalid or not yet available, falling back to DOM rendering
  • zooming: Zooming in or out, will use fast canvas placeholder rendering
  • rendering: Currently rendering to a bitmap (async operation in progress)
  • ready: Bitmap is valid and rendered, DOM elements can be safely removed

WorkerToHostMessage ​

WorkerToHostMessage = MessageBitmapPainted | MessagePaintError

Variables ​

BlockLayoutHandlersIdentifier ​

const BlockLayoutHandlersIdentifier: ServiceIdentifier<BlockLayoutHandlerExtension<BlockLayout>> & <U>(variant) => ServiceIdentifier<U>

BlockPainterProvider ​

const BlockPainterProvider: ServiceIdentifier<BlockLayoutPainter> & <U>(variant) => ServiceIdentifier<U>

TurboRendererConfigFactory ​

const TurboRendererConfigFactory: ConfigFactory<TurboRendererConfig>

ViewportTurboRendererIdentifier ​

const ViewportTurboRendererIdentifier: ServiceIdentifier<GfxExtension>

Functions ​

BlockLayoutPainterExtension() ​

BlockLayoutPainterExtension(type, painter): ExtensionType

Parameters ​

type ​

string

painter ​

() => BlockLayoutPainter

Returns ​

ExtensionType

getBaseline() ​

getBaseline(fontSize): number

Parameters ​

fontSize ​

number

Returns ​

number

getSentenceRects() ​

getSentenceRects(element, sentence): TextRect[]

Parameters ​

element ​

Element

sentence ​

string

Returns ​

TextRect[]

segmentSentences() ​

segmentSentences(text): string[]

Parameters ​

text ​

string

Returns ​

string[]

Copyright © 2022-present Toeverything