@nasser-sw/fabric 7.0.0-beta1

package/src/env/browser.ts

@@ -0,0 +1,21 @@
+/* eslint-disable no-restricted-globals */
+import { WebGLProbe } from '../filters/GLProbes/WebGLProbe';
+import type { TCopyPasteData, TFabricEnv } from './types';
+
+const copyPasteData: TCopyPasteData = {};
+
+export const getEnv = (): TFabricEnv => {
+  return {
+    document,
+    window,
+    isTouchSupported:
+      'ontouchstart' in window ||
+      'ontouchstart' in document ||
+      (window && window.navigator && window.navigator.maxTouchPoints > 0),
+    WebGLProbe: new WebGLProbe(),
+    dispose() {
+      // noop
+    },
+    copyPasteData,
+  };
+};

package/src/env/env.spec.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+
+describe('env', () => {
+  it('passes', () => {
+    expect(true).toBeTruthy();
+  });
+  // afterEach(() => {
+  //   delete globalThis.window;
+  //   delete globalThis.document;
+  // });
+  // it('import/require of `main` field of package.json throws', async () => {
+  //   expect(import('../..'), 'should not resolve main').rejects.toBe(1);
+  //   expect(() => require('../..'), 'should not resolve main').toThrow();
+  // });
+  // it('import/require sets env', async () => {
+  //   globalThis.window = { devicePixelRatio: 1.25 };
+  //   globalThis.document = { foo: 'bar' };
+  //   const imported = await import('../../index.node');
+  //   const required = require('../../index.node');
+  //   expect(imported.getEnv().document.foo, 'should be node env').toBe(
+  //     undefined,
+  //   );
+  //   expect(required.getEnv().document.foo, 'should be node env').toBe(
+  //     undefined,
+  //   );
+  // });
+  // it('SSR: importing fabric before window/document are defined', async () => {
+  //   const imported = await import('../../dist/index.js');
+  //   const required = require('../../dist/index.js');
+  //   expect(globalThis.window, 'no window').toBeFalsy();
+  //   expect(globalThis.document, 'no document').toBeFalsy();
+  //   const win = { devicePixelRatio: 1.25 };
+  //   const doc = { foo: 'bar' };
+  //   globalThis.window = win;
+  //   globalThis.document = doc;
+  //   [imported, required].forEach((fabric) => {
+  //     expect(fabric.getEnv().window, 'window should match').toBe(win);
+  //     expect(fabric.getEnv().document, 'document should match').toBe(doc);
+  //   });
+  // });
+  // describe('browser', () => {
+  //   it('browser env', () => {
+  //     expect(fabric.getFabricWindow(), 'window should be set').toBe(window);
+  //     expect(fabric.getFabricDocument(), 'document should be set').toBe(document);
+  //   });
+  // });
+});

package/src/env/index.ts

@@ -0,0 +1,47 @@
+/**
+ * This file is consumed by fabric.
+ * The `./node` and `./browser` files define the env variable that is used by this module.
+ * The `./browser` module is defined to be the default env and doesn't set the env at all.
+ * This is done in order to support isomorphic usage for browser and node applications
+ * since window and document aren't defined at time of import in SSR, we can't set env so we avoid it by deferring to the default env.
+ */
+
+import { config } from '../config';
+import { getEnv as getBrowserEnv } from './browser';
+import type { TFabricEnv } from './types';
+import type { DOMWindow } from 'jsdom';
+
+let env: TFabricEnv;
+
+/**
+ * Sets the environment variables used by fabric.\
+ * This is exposed for special cases, such as configuring a test environment, and should be used with care.
+ *
+ * **CAUTION**: Must be called before using the package.
+ *
+ * @example
+ * <caption>Passing `window` and `document` objects to fabric (in case they are mocked or something)</caption>
+ * import { getEnv, setEnv } from 'fabric';
+ * // we want fabric to use the `window` and `document` objects exposed by the environment we are running in.
+ * setEnv({ ...getEnv(), window, document });
+ * // done with setup, using fabric is now safe
+ */
+export const setEnv = (value: TFabricEnv) => {
+  env = value;
+};
+
+/**
+ * In order to support SSR we **MUST** access the browser env only after the window has loaded
+ */
+export const getEnv = () => env || (env = getBrowserEnv());
+
+export const getFabricDocument = (): Document => getEnv().document;
+
+export const getFabricWindow = (): (Window & typeof globalThis) | DOMWindow =>
+  getEnv().window;
+
+/**
+ * @returns the config value if defined, fallbacks to the environment value
+ */
+export const getDevicePixelRatio = () =>
+  Math.max(config.devicePixelRatio ?? getFabricWindow().devicePixelRatio, 1);

package/src/env/node.ts

@@ -0,0 +1,50 @@
+/* eslint-disable no-restricted-globals */
+import type { Canvas as NodeCanvas } from 'canvas';
+import { JSDOM } from 'jsdom';
+// @ts-expect-error internal import
+import utils from 'jsdom/lib/jsdom/living/generated/utils.js';
+import { NodeGLProbe } from '../filters/GLProbes/NodeGLProbe';
+import type { TCopyPasteData, TFabricEnv } from './types';
+
+const { implForWrapper: jsdomImplForWrapper } = utils;
+
+const copyPasteData: TCopyPasteData = {};
+
+const { window: JSDOMWindow } = new JSDOM(
+  decodeURIComponent(
+    '%3C!DOCTYPE%20html%3E%3Chtml%3E%3Chead%3E%3C%2Fhead%3E%3Cbody%3E%3C%2Fbody%3E%3C%2Fhtml%3E',
+  ),
+  {
+    resources: 'usable',
+    // needed for `requestAnimationFrame`
+    pretendToBeVisual: true,
+  },
+);
+
+export const getNodeCanvas = (canvasEl: HTMLCanvasElement) => {
+  const impl = jsdomImplForWrapper(canvasEl);
+  return (impl._canvas || impl._image) as NodeCanvas;
+};
+
+export const dispose = (element: Element) => {
+  const impl = jsdomImplForWrapper(element);
+  if (impl) {
+    impl._image = null;
+    impl._canvas = null;
+    // unsure if necessary
+    impl._currentSrc = null;
+    impl._attributes = null;
+    impl._classList = null;
+  }
+};
+
+export const getEnv = (): TFabricEnv => {
+  return {
+    document: JSDOMWindow.document,
+    window: JSDOMWindow,
+    isTouchSupported: false,
+    WebGLProbe: new NodeGLProbe(),
+    dispose,
+    copyPasteData,
+  };
+};

package/src/env/types.ts

@@ -0,0 +1,16 @@
+import type { GLProbe } from '../filters/GLProbes/GLProbe';
+import type { DOMWindow } from 'jsdom';
+import type { TextStyleDeclaration } from '../shapes/Text/StyledText';
+
+export type TCopyPasteData = {
+  copiedText?: string;
+  copiedTextStyle?: TextStyleDeclaration[];
+};
+export type TFabricEnv = {
+  readonly document: Document;
+  readonly window: (Window & typeof globalThis) | DOMWindow;
+  readonly isTouchSupported: boolean;
+  WebGLProbe: GLProbe;
+  dispose(element: Element): void;
+  copyPasteData: TCopyPasteData;
+};

package/src/filters/BaseFilter.spec.ts

@@ -0,0 +1,16 @@
+import { BaseFilter } from './BaseFilter';
+
+import { describe, expect, it } from 'vitest';
+
+class SimpleFilter extends BaseFilter<'?'> {
+  static type = '?';
+  declare property: string;
+}
+
+describe('Extended filters', () => {
+  it('can export', () => {
+    const f = new SimpleFilter();
+    const serialized = f.toObject();
+    expect(serialized).toEqual({ type: '?' });
+  });
+});

package/src/filters/BaseFilter.ts

@@ -0,0 +1,416 @@
+import { getEnv } from '../env';
+import type {
+  T2DPipelineState,
+  TWebGLAttributeLocationMap,
+  TWebGLPipelineState,
+  TWebGLProgramCacheItem,
+  TWebGLUniformLocationMap,
+} from './typedefs';
+import { isWebGLPipelineState } from './utils';
+import {
+  highPsourceCode,
+  identityFragmentShader,
+  vertexSource,
+} from './shaders/baseFilter';
+import type { Abortable } from '../typedefs';
+import { FabricError } from '../util/internals/console';
+import { createCanvasElementFor } from '../util/misc/dom';
+
+const regex = new RegExp(highPsourceCode, 'g');
+
+export class BaseFilter<
+  Name extends string,
+  OwnProps extends Record<string, any> = object,
+  SerializedProps extends Record<string, any> = OwnProps,
+> {
+  /**
+   * Filter type
+   */
+  get type(): Name {
+    return (this.constructor as typeof BaseFilter).type as Name;
+  }
+
+  /**
+   * The class type. Used to identify which class this is.
+   * This is used for serialization purposes and internally it can be used
+   * to identify classes. As a developer you could use `instance of Class`
+   * but to avoid importing all the code and blocking tree shaking we try
+   * to avoid doing that.
+   */
+  static type = 'BaseFilter';
+
+  /**
+   * Contains the uniform locations for the fragment shader.
+   * uStepW and uStepH are handled by the BaseFilter, each filter class
+   * needs to specify all the one that are needed
+   */
+  static uniformLocations: string[] = [];
+
+  declare static defaults: Record<string, unknown>;
+
+  /**
+   * Constructor
+   * @param {Object} [options] Options object
+   */
+  constructor({
+    type,
+    ...options
+  }: { type?: never } & Partial<OwnProps> & Record<string, any> = {}) {
+    Object.assign(
+      this,
+      (this.constructor as typeof BaseFilter).defaults,
+      options,
+    );
+  }
+
+  protected getFragmentSource(): string {
+    return identityFragmentShader;
+  }
+
+  getVertexSource(): string {
+    return vertexSource;
+  }
+
+  /**
+   * Compile this filter's shader program.
+   *
+   * @param {WebGLRenderingContext} gl The GL canvas context to use for shader compilation.
+   * @param {String} fragmentSource fragmentShader source for compilation
+   * @param {String} vertexSource vertexShader source for compilation
+   */
+  createProgram(
+    gl: WebGLRenderingContext,
+    fragmentSource: string = this.getFragmentSource(),
+    vertexSource: string = this.getVertexSource(),
+  ) {
+    const {
+      WebGLProbe: { GLPrecision = 'highp' },
+    } = getEnv();
+    if (GLPrecision !== 'highp') {
+      fragmentSource = fragmentSource.replace(
+        regex,
+        highPsourceCode.replace('highp', GLPrecision),
+      );
+    }
+    const vertexShader = gl.createShader(gl.VERTEX_SHADER);
+    const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
+    const program = gl.createProgram();
+
+    if (!vertexShader || !fragmentShader || !program) {
+      throw new FabricError(
+        'Vertex, fragment shader or program creation error',
+      );
+    }
+    gl.shaderSource(vertexShader, vertexSource);
+    gl.compileShader(vertexShader);
+    if (!gl.getShaderParameter(vertexShader, gl.COMPILE_STATUS)) {
+      throw new FabricError(
+        `Vertex shader compile error for ${this.type}: ${gl.getShaderInfoLog(
+          vertexShader,
+        )}`,
+      );
+    }
+
+    gl.shaderSource(fragmentShader, fragmentSource);
+    gl.compileShader(fragmentShader);
+    if (!gl.getShaderParameter(fragmentShader, gl.COMPILE_STATUS)) {
+      throw new FabricError(
+        `Fragment shader compile error for ${this.type}: ${gl.getShaderInfoLog(
+          fragmentShader,
+        )}`,
+      );
+    }
+
+    gl.attachShader(program, vertexShader);
+    gl.attachShader(program, fragmentShader);
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      throw new FabricError(
+        `Shader link error for "${this.type}" ${gl.getProgramInfoLog(program)}`,
+      );
+    }
+
+    const uniformLocations = this.getUniformLocations(gl, program) || {};
+    uniformLocations.uStepW = gl.getUniformLocation(program, 'uStepW');
+    uniformLocations.uStepH = gl.getUniformLocation(program, 'uStepH');
+
+    return {
+      program,
+      attributeLocations: this.getAttributeLocations(gl, program),
+      uniformLocations,
+    };
+  }
+
+  /**
+   * Return a map of attribute names to WebGLAttributeLocation objects.
+   *
+   * @param {WebGLRenderingContext} gl The canvas context used to compile the shader program.
+   * @param {WebGLShaderProgram} program The shader program from which to take attribute locations.
+   * @returns {Object} A map of attribute names to attribute locations.
+   */
+  getAttributeLocations(
+    gl: WebGLRenderingContext,
+    program: WebGLProgram,
+  ): TWebGLAttributeLocationMap {
+    return {
+      aPosition: gl.getAttribLocation(program, 'aPosition'),
+    };
+  }
+
+  /**
+   * Return a map of uniform names to WebGLUniformLocation objects.
+   *
+   * @param {WebGLRenderingContext} gl The canvas context used to compile the shader program.
+   * @param {WebGLShaderProgram} program The shader program from which to take uniform locations.
+   * @returns {Object} A map of uniform names to uniform locations.
+   */
+  getUniformLocations(
+    gl: WebGLRenderingContext,
+    program: WebGLProgram,
+  ): TWebGLUniformLocationMap {
+    const locations = (this.constructor as unknown as typeof BaseFilter<string>)
+      .uniformLocations;
+
+    const uniformLocations: Record<string, WebGLUniformLocation | null> = {};
+    for (let i = 0; i < locations.length; i++) {
+      uniformLocations[locations[i]] = gl.getUniformLocation(
+        program,
+        locations[i],
+      );
+    }
+    return uniformLocations;
+  }
+
+  /**
+   * Send attribute data from this filter to its shader program on the GPU.
+   *
+   * @param {WebGLRenderingContext} gl The canvas context used to compile the shader program.
+   * @param {Object} attributeLocations A map of shader attribute names to their locations.
+   */
+  sendAttributeData(
+    gl: WebGLRenderingContext,
+    attributeLocations: Record<string, number>,
+    aPositionData: Float32Array,
+  ) {
+    const attributeLocation = attributeLocations.aPosition;
+    const buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.enableVertexAttribArray(attributeLocation);
+    gl.vertexAttribPointer(attributeLocation, 2, gl.FLOAT, false, 0, 0);
+    gl.bufferData(gl.ARRAY_BUFFER, aPositionData, gl.STATIC_DRAW);
+  }
+
+  _setupFrameBuffer(options: TWebGLPipelineState) {
+    const gl = options.context;
+    if (options.passes > 1) {
+      const width = options.destinationWidth;
+      const height = options.destinationHeight;
+      if (options.sourceWidth !== width || options.sourceHeight !== height) {
+        gl.deleteTexture(options.targetTexture);
+        options.targetTexture = options.filterBackend.createTexture(
+          gl,
+          width,
+          height,
+        );
+      }
+      gl.framebufferTexture2D(
+        gl.FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT0,
+        gl.TEXTURE_2D,
+        options.targetTexture,
+        0,
+      );
+    } else {
+      // draw last filter on canvas and not to framebuffer.
+      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+      gl.finish();
+    }
+  }
+
+  _swapTextures(options: TWebGLPipelineState) {
+    options.passes--;
+    options.pass++;
+    const temp = options.targetTexture;
+    options.targetTexture = options.sourceTexture;
+    options.sourceTexture = temp;
+  }
+
+  /**
+   * Generic isNeutral implementation for one parameter based filters.
+   * Used only in image applyFilters to discard filters that will not have an effect
+   * on the image
+   * Other filters may need their own version ( ColorMatrix, HueRotation, gamma, ComposedFilter )
+   * @param {Object} options
+   **/
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  isNeutralState(options?: any): boolean {
+    return false;
+  }
+
+  /**
+   * Apply this filter to the input image data provided.
+   *
+   * Determines whether to use WebGL or Canvas2D based on the options.webgl flag.
+   *
+   * @param {Object} options
+   * @param {Number} options.passes The number of filters remaining to be executed
+   * @param {Boolean} options.webgl Whether to use webgl to render the filter.
+   * @param {WebGLTexture} options.sourceTexture The texture setup as the source to be filtered.
+   * @param {WebGLTexture} options.targetTexture The texture where filtered output should be drawn.
+   * @param {WebGLRenderingContext} options.context The GL context used for rendering.
+   * @param {Object} options.programCache A map of compiled shader programs, keyed by filter type.
+   */
+  applyTo(options: TWebGLPipelineState | T2DPipelineState) {
+    if (isWebGLPipelineState(options)) {
+      this._setupFrameBuffer(options);
+      this.applyToWebGL(options);
+      this._swapTextures(options);
+    } else {
+      this.applyTo2d(options);
+    }
+  }
+
+  applyTo2d(_options: T2DPipelineState): void {
+    // override by subclass
+  }
+
+  /**
+   * Returns a string that represent the current selected shader code for the filter.
+   * Used to force recompilation when parameters change or to retrieve the shader from cache
+   * @type string
+   **/
+  getCacheKey(): string {
+    return this.type;
+  }
+
+  /**
+   * Retrieves the cached shader.
+   * @param {Object} options
+   * @param {WebGLRenderingContext} options.context The GL context used for rendering.
+   * @param {Object} options.programCache A map of compiled shader programs, keyed by filter type.
+   * @return {WebGLProgram} the compiled program shader
+   */
+  retrieveShader(options: TWebGLPipelineState): TWebGLProgramCacheItem {
+    const key = this.getCacheKey();
+    if (!options.programCache[key]) {
+      options.programCache[key] = this.createProgram(options.context);
+    }
+    return options.programCache[key];
+  }
+
+  /**
+   * Apply this filter using webgl.
+   *
+   * @param {Object} options
+   * @param {Number} options.passes The number of filters remaining to be executed
+   * @param {Boolean} options.webgl Whether to use webgl to render the filter.
+   * @param {WebGLTexture} options.originalTexture The texture of the original input image.
+   * @param {WebGLTexture} options.sourceTexture The texture setup as the source to be filtered.
+   * @param {WebGLTexture} options.targetTexture The texture where filtered output should be drawn.
+   * @param {WebGLRenderingContext} options.context The GL context used for rendering.
+   * @param {Object} options.programCache A map of compiled shader programs, keyed by filter type.
+   */
+  applyToWebGL(options: TWebGLPipelineState) {
+    const gl = options.context;
+    const shader = this.retrieveShader(options);
+    if (options.pass === 0 && options.originalTexture) {
+      gl.bindTexture(gl.TEXTURE_2D, options.originalTexture);
+    } else {
+      gl.bindTexture(gl.TEXTURE_2D, options.sourceTexture);
+    }
+    gl.useProgram(shader.program);
+    this.sendAttributeData(gl, shader.attributeLocations, options.aPosition);
+
+    gl.uniform1f(shader.uniformLocations.uStepW, 1 / options.sourceWidth);
+    gl.uniform1f(shader.uniformLocations.uStepH, 1 / options.sourceHeight);
+
+    this.sendUniformData(gl, shader.uniformLocations);
+    gl.viewport(0, 0, options.destinationWidth, options.destinationHeight);
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+  }
+
+  bindAdditionalTexture(
+    gl: WebGLRenderingContext,
+    texture: WebGLTexture,
+    textureUnit: number,
+  ) {
+    gl.activeTexture(textureUnit);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    // reset active texture to 0 as usual
+    gl.activeTexture(gl.TEXTURE0);
+  }
+
+  unbindAdditionalTexture(gl: WebGLRenderingContext, textureUnit: number) {
+    gl.activeTexture(textureUnit);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.activeTexture(gl.TEXTURE0);
+  }
+
+  /**
+   * Send uniform data from this filter to its shader program on the GPU.
+   *
+   * Intended to be overridden by subclasses.
+   *
+   * @param {WebGLRenderingContext} _gl The canvas context used to compile the shader program.
+   * @param {Object} _uniformLocations A map of shader uniform names to their locations.
+   */
+  sendUniformData(
+    _gl: WebGLRenderingContext,
+    _uniformLocations: TWebGLUniformLocationMap,
+  ): void {
+    // override by subclass
+  }
+
+  /**
+   * If needed by a 2d filter, this functions can create an helper canvas to be used
+   * remember that options.targetCanvas is available for use till end of chain.
+   */
+  createHelpLayer(options: T2DPipelineState) {
+    if (!options.helpLayer) {
+      const { sourceWidth, sourceHeight } = options;
+      const helpLayer = createCanvasElementFor({
+        width: sourceWidth,
+        height: sourceHeight,
+      });
+      options.helpLayer = helpLayer;
+    }
+  }
+
+  /**
+   * Returns object representation of an instance
+   * It will automatically export the default values of a filter,
+   * stored in the static defaults property.
+   * @return {Object} Object representation of an instance
+   */
+  toObject(): { type: Name } & SerializedProps {
+    const defaultKeys = Object.keys(
+      (this.constructor as typeof BaseFilter).defaults || {},
+    ) as (keyof SerializedProps)[];
+
+    return {
+      type: this.type,
+      ...defaultKeys.reduce<SerializedProps>((acc, key) => {
+        acc[key] = this[
+          key as keyof this
+        ] as unknown as (typeof acc)[typeof key];
+        return acc;
+      }, {} as SerializedProps),
+    };
+  }
+
+  /**
+   * Returns a JSON representation of an instance
+   * @return {Object} JSON
+   */
+  toJSON() {
+    // delegate, not alias
+    return this.toObject();
+  }
+
+  static async fromObject(
+    { type, ...filterOptions }: Record<string, any>,
+    _options?: Abortable,
+  ): Promise<BaseFilter<string>> {
+    return new this(filterOptions);
+  }
+}