Merge pull request #90 from ashtonisher/feature

feat: Add 3D rotation effect option for snowflakes

Author: cahilfoley

README.md

@@ -66,11 +66,12 @@ All available properties are detailed below.
 | `images`          | An array of images that will be rendered as the snowflakes instead of the default circle shapes.                                                                                                                                                                                         | `undefined`   |
 | `radius`          | The minimum and maximum radius of the snowflake in pixels.<br/><br/>The value for each snowflake will be randomly selected within this range.                                                                                                                                            | `[0.5, 3.0]`  |
 | `rotationSpeed`   | The minimum and maximum rotation speed of the snowflake (in degrees of rotation per frame).<br/><br/>The rotation speed determines how quickly the snowflake rotates when an image is being rendered.<br/><br/>The value for each snowflake will be randomly selected within this range. | `[-1.0, 1.0]` |
+| `enable3DRotation`| Enable 3D rotation effect (like falling leaves).<br/><br/>When enabled, snowflakes will rotate on X, Y, and Z axes, creating a more realistic 3D tumbling effect.<br/><br/>Works with both images and circles. | `false`       |
 | `snowflakeCount`  | The number of snowflakes to be rendered.                                                                                                                                                                                                                                                 | `150`         |
 | `speed`           | The minimum and maximum speed of the snowflake (in pixels per frame).<br/><br/>The speed determines how quickly the snowflake moves along the y axis (vertical speed).<br/><br/>The value for each snowflake will be randomly selected within this range.                                | `[1.0, 3.0]`  |
 | `style`           | Any style properties that will be passed to the canvas element.                                                                                                                                                                                                                          | `undefined`   |
 | `wind`            | The minimum and maximum wind of the snowflake (in pixels per frame).<br/><br/>The wind determines how quickly the snowflake moves along the x axis (horizontal speed).<br/><br/>The value for each snowflake will be randomly selected within this range.                                | `[-0.5, 2.0]` |
-| `opacity`            | The minimum and maximum opacity of the snowflake.<br/><br/>The value for each snowflake will be randomly selected within this range.                                | `[1, 1]` |
+| `opacity`         | The minimum and maximum opacity of the snowflake.<br/><br/>The value for each snowflake will be randomly selected within this range.                                                                                                                                                     | `[1, 1]`      |
 
 ## Using Images
 

packages/demo/src/App.tsx

@@ -14,7 +14,7 @@ snowflake.src = logo
 const images = [snowflake]
 
 const App = () => {
-  const { color, snowflakeCount, radius, speed, wind, useImages, opacity } = useSettingsStore()
+  const { color, snowflakeCount, radius, speed, wind, useImages, opacity, enable3DRotation } = useSettingsStore()
 
   return (
     <div className="app">
@@ -26,6 +26,7 @@ const App = () => {
         wind={wind}
         images={useImages ? images : undefined}
         opacity={opacity}
+        enable3DRotation={enable3DRotation}
       />
       <a className="title" href={githubURL} style={{ color }}>
         <img src={logo} alt="Snowflake Logo" />

packages/demo/src/components/Settings/Settings.tsx

@@ -106,6 +106,17 @@ const Settings = () => {
               label="Use Images"
             />
           </div>
+          <div>
+            <FormControlLabel
+              control={
+                <Checkbox
+                  checked={settings.enable3DRotation || false}
+                  onChange={(event) => settings.update({ enable3DRotation: event.target.checked })}
+                />
+              }
+              label="Enable 3D Rotation"
+            />
+          </div>
           {settings.useImages ? (
             <>
               <div>

packages/demo/src/settings.tsx

@@ -16,6 +16,7 @@ export const useSettingsStore = create<SnowfallSettings>((set) => ({
   rotationSpeed: [-1.0, 1.0],
   opacity: [0.1, 0.2],
   useImages: false,
+  enable3DRotation: false,
   update: (changes) => set(changes),
   setUseImages: (useImages) => {
     if (useImages) {

packages/react-snowfall/lib/Snowfall.d.ts

@@ -6,5 +6,5 @@ export interface SnowfallProps extends Partial<SnowfallCanvasConfig> {
      */
     style?: React.CSSProperties;
 }
-export declare const Snowfall: ({ color, changeFrequency, radius, speed, wind, rotationSpeed, opacity, snowflakeCount, images, style, }?: SnowfallProps) => JSX.Element;
+export declare const Snowfall: ({ color, changeFrequency, radius, speed, wind, rotationSpeed, opacity, snowflakeCount, images, enable3DRotation, style, }?: SnowfallProps) => JSX.Element;
 export default Snowfall;

packages/react-snowfall/lib/Snowfall.js

@@ -64,6 +64,15 @@ export interface SnowflakeProps {
      * The default value is `[1, 1]`.
      */
     opacity: [number, number];
+    /**
+     * Enable 3D rotation effect (like falling leaves).
+     *
+     * When enabled, snowflakes will rotate on X and Y axes in addition to Z axis,
+     * creating a more realistic 3D tumbling effect.
+     *
+     * The default value is `false`.
+     */
+    enable3DRotation?: boolean;
 }
 export type SnowflakeConfig = Partial<SnowflakeProps>;
 export declare const defaultConfig: SnowflakeProps;
@@ -90,6 +99,15 @@ declare class Snowflake {
     private updateTargetParams;
     update(offsetWidth: number, offsetHeight: number, framesPassed?: number): void;
     private getImageOffscreenCanvas;
+    /**
+     * Applies 3D rotation transform to the canvas context.
+     * This method calculates and applies the transformation matrix for 3D rotation effects.
+     *
+     * @param ctx The canvas context to apply the transform to
+     * @param x The x position to translate to
+     * @param y The y position to translate to
+     */
+    private apply3DTransform;
     /**
      * Draws a circular snowflake to the canvas.
      *
@@ -107,6 +125,15 @@ declare class Snowflake {
      * @param ctx The canvas context to draw to
      */
     drawCircle(ctx: CanvasRenderingContext2D): void;
+    /**
+     * Draws a circular snowflake with 3D rotation effect to the canvas.
+     *
+     * This method is used when 3D rotation is enabled and images are not being used.
+     *
+     * @param ctx The canvas context to draw to
+     * @param color The color to fill the circle with
+     */
+    drawCircle3D(ctx: CanvasRenderingContext2D, color: string): void;
     /**
      * Draws an image-based snowflake to the canvas.
      *