docs: update README

Bernankez · Apr 18, 2024 · 1809ae6 · 1809ae6
1 parent ce642f8
commit 1809ae6
Show file tree

Hide file tree

Showing 8 changed files with 2,079 additions and 5 deletions.
diff --git a/README.md b/README.md
diff --git a/packages/core/README.md b/packages/core/README.md
diff --git a/packages/react/README.md b/packages/react/README.md
diff --git a/packages/vue/README.md b/packages/vue/README.md
diff --git a/playground/public/favicon-paw.svg b/playground/public/favicon-paw.svg
diff --git a/playground/src/layouts/Layout.astro b/playground/src/layouts/Layout.astro
@@ -12,7 +12,7 @@ const { title = "Backmoji" } = Astro.props;
     <meta charset="UTF-8" />
     <meta name="description" content="Astro description" />
     <meta name="viewport" content="width=device-width" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/svg+xml" href="/favicon-paw.svg" />
     <meta name="generator" content={Astro.generator} />
     <title>{title}</title>
   </head>

diff --git a/playground/src/pages/explainations.png b/playground/src/pages/explainations.png
diff --git a/playground/src/pages/index.mdx b/playground/src/pages/index.mdx
@@ -2,6 +2,8 @@
 layout: ./_Index.astro
 ---
 
+> **This library is still under development, and the APIs are not stable yet.**
+
 ## Install
 
 ```sh
@@ -267,7 +269,7 @@ render();
 
 ### With animation
 
-`backmoji` itself does not provide any animation-related functionality, but through `customRender`, you can implement your own animatino functionality, just like the animated background on this website. Here is a demonstration related to animation functionality.
+`backmoji` itself does not provide any animation-related functionality, but through `customRender`, you can implement your own animation functionality, just like the animated background on this website. Here is a demonstration related to animation functionality.
 
 import AnimationPattern from "@/demos/AnimationPattern.astro";
 
@@ -438,7 +440,90 @@ parent.appendChild(statDom);
 play();
 ```
 
-### Options
+## Customize
+
+You can create your own `renderer` if the provided renderers do not meet your needs. See [renderer.ts](https://github.com/Bernankez/Backmoji/blob/master/packages/core/src/renderer.ts) for more details.
+
+## Options
+
+### `backmoji`
+
+```ts
+declare function backmoji(canvas: Awaitable<HTMLCanvasElement>, renderer: Awaitable<Renderer>, options?: BackmojiOptions): {
+  render: () => Promise<void>;
+  setOptions: (options: BackmojiOptions, combine?: boolean) => void;
+  /*
+  * Set the size of the canvas. It handles device pixel ratio automatically.
+  */
+  setSize: (width: number | undefined, height: number | undefined) => Promise<void>;
+};
+
+interface BackmojiOptions {
+  degree?: number;
+  rowGap?: number;
+  columnGap?: number;
+}
+
+type Renderer = (context: RendererContext) => void;
+
+interface RendererContext {
+  ctx: CanvasRenderingContext2D;
+  width: number;
+  height: number;
+  rowGap: number;
+  columnGap: number;
+  degree: number;
+  angle: number;
+  /*
+  * Measure size of texts, using CanvasRenderingContext2D.measureText underhood
+  */
+  measureText: (text: string) => {
+    width: number;
+    fontHeight: number;
+    height: number;
+  };
+  /*
+  * Calculate how many items should be rendered each row
+  */
+  calculateRenderCount: (renderItemWidth: number, renderItemHeight: number) => number[] & {
+    row: number;
+    column: number;
+  };
+  /*
+  * Calculate the translate after rotation
+  */
+  calculateTranslate: () => number[] & {
+    x: number;
+    y: number;
+  };
+}
+```
+
+### renderer
+
+```ts
+interface CreateTextRendererOptions {
+  font?: string;
+  customRender?: (context: RenderContext<string>) => void;
+}
+/*
+* The default render function if no customRender provided
+*/
+declare function textRender(context: RenderContext<string>): void;
+declare function createTextRenderer(text: string, options?: CreateTextRendererOptions): Renderer;
+interface CreateImageRendererOptions {
+  customRender?: (context: RenderContext<HTMLImageElement>) => void;
+}
+```
+
+```ts
+/*
+* The default render function if no customRender provided
+*/
+declare function imageRender(context: RenderContext<HTMLImageElement>): void;
+declare function createImageRenderer(img: HTMLImageElement, options?: CreateImageRendererOptions): Renderer;
+```
+
+The following image explains the meanings of various attribute values:
 
-// TODO
-// explaination for options
+![options](./explainations.png)