@guinetik/gcanvas 1.0.0 → 1.0.2

package/types/shapes.d.ts

@@ -713,21 +713,56 @@ export class PatternRectangle extends Rectangle {
 
 /** Options for ImageShape */
 export interface ImageShapeOptions extends ShapeOptions {
-  /** Image source URL */
-  src?: string;
-  /** Image element */
-  image?: HTMLImageElement;
+  /** Anchor point for positioning (e.g., "center", "top-left") */
+  anchor?: string;
+  /** Enable image smoothing (default: true) */
+  smoothing?: boolean;
 }
 
+/** Type for bitmap sources that ImageShape accepts */
+export type BitmapSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | HTMLVideoElement | ImageData;
+
 /**
- * Image shape.
+ * Image shape for rendering arbitrary pixel buffers.
+ * Supports HTMLImageElement, HTMLCanvasElement, ImageBitmap, HTMLVideoElement, and ImageData.
+ *
+ * @example
+ * const data = Painter.img.getImageData(0, 0, 320, 200);
+ * const shape = new ImageShape(data, { x: 100, y: 50, anchor: "center" });
+ * scene.add(shape);
  */
 export class ImageShape extends Shape {
-  constructor(options?: ImageShapeOptions);
+  /**
+   * Create an ImageShape.
+   * @param bitmap - Image source (HTMLImageElement, HTMLCanvasElement, ImageBitmap, HTMLVideoElement, or ImageData)
+   * @param options - Shape options including anchor and smoothing
+   */
+  constructor(bitmap: BitmapSource | null, options?: ImageShapeOptions);
+
+  /** The internal bitmap */
+  get bitmap(): BitmapSource | null;
+  set bitmap(v: BitmapSource | null);
+
+  /** Anchor position (e.g., "center", "top-left") */
+  anchor: string;
 
-  /** The image element */
-  get image(): HTMLImageElement | null;
-  set image(v: HTMLImageElement | null);
+  /** Whether image smoothing is enabled */
+  smoothing: boolean;
+
+  /**
+   * Update the canvas buffer for ImageData sources.
+   * @param bitmap - ImageData to buffer
+   */
+  buffer(bitmap: ImageData): void;
+
+  /** Reset the image to an empty state */
+  reset(): void;
+
+  /**
+   * Set the anchor point.
+   * @param anchor - Anchor position string
+   */
+  setAnchor(anchor: string): void;
 }
 
 // ==========================================================================
@@ -801,6 +836,69 @@ export class Sphere extends Shape {
   constructor(radius: number, options?: ShapeOptions);
 }
 
+/** Options for Sphere3D */
+export interface Sphere3DOptions extends ShapeOptions {
+  /** Sphere radius */
+  radius?: number;
+  /** Number of latitude segments */
+  latSegments?: number;
+  /** Number of longitude segments */
+  lonSegments?: number;
+  /** Base color */
+  color?: string;
+  /** Light direction [x, y, z] */
+  lightDirection?: [number, number, number];
+  /** Ambient light intensity (0-1) */
+  ambientLight?: number;
+  /** Whether to use glow effect */
+  glow?: boolean;
+  /** Glow color */
+  glowColor?: string;
+  /** Glow intensity */
+  glowIntensity?: number;
+  /** Whether to use wireframe */
+  wireframe?: boolean;
+  /** Wireframe color */
+  wireframeColor?: string;
+}
+
+/**
+ * 3D sphere with Camera3D projection support.
+ * Renders a proper 3D sphere with lighting and optional effects.
+ *
+ * @example
+ * const sphere = new Sphere3D({
+ *   x: 0, y: 0, z: 0,
+ *   radius: 100,
+ *   color: '#ff6600',
+ *   glow: true
+ * });
+ */
+export class Sphere3D extends Shape {
+  /** Sphere radius */
+  radius: number;
+  /** Z position in 3D space */
+  z: number;
+  /** Camera3D instance for projection */
+  camera: any;
+
+  constructor(options?: Sphere3DOptions);
+
+  /**
+   * Set the camera for 3D projection.
+   * @param camera - Camera3D instance
+   */
+  setCamera(camera: any): Sphere3D;
+
+  /**
+   * Set position in 3D space.
+   * @param x - X position
+   * @param y - Y position
+   * @param z - Z position
+   */
+  setPosition(x: number, y: number, z: number): Sphere3D;
+}
+
 // ==========================================================================
 // Text Shapes
 // ==========================================================================

package/types/util.d.ts

@@ -251,3 +251,356 @@ export function gridLayout(
   items: LayoutItem[],
   options?: GridLayoutOptions
 ): LayoutResult;
+
+// ==========================================================================
+// Camera3D
+// ==========================================================================
+
+/** Options for Camera3D */
+export interface Camera3DOptions {
+  /** Initial X rotation (tilt up/down) in radians */
+  rotationX?: number;
+  /** Initial Y rotation (spin left/right) in radians */
+  rotationY?: number;
+  /** Initial Z rotation (roll) in radians */
+  rotationZ?: number;
+  /** Initial X position in world space */
+  x?: number;
+  /** Initial Y position in world space */
+  y?: number;
+  /** Initial Z position in world space */
+  z?: number;
+  /** Perspective distance (higher = less distortion, default: 800) */
+  perspective?: number;
+  /** Mouse drag sensitivity (default: 0.005) */
+  sensitivity?: number;
+  /** Minimum X rotation limit (default: -1.5) */
+  minRotationX?: number;
+  /** Maximum X rotation limit (default: 1.5) */
+  maxRotationX?: number;
+  /** Whether to clamp X rotation (default: true) */
+  clampX?: boolean;
+  /** Enable auto-rotation (default: false) */
+  autoRotate?: boolean;
+  /** Auto-rotation speed in radians per second (default: 0.5) */
+  autoRotateSpeed?: number;
+  /** Auto-rotation axis: 'x', 'y', or 'z' */
+  autoRotateAxis?: 'x' | 'y' | 'z';
+  /** Enable inertia/momentum (default: false) */
+  inertia?: boolean;
+  /** Velocity decay per frame (default: 0.92) */
+  friction?: number;
+  /** Multiplier for initial throw velocity (default: 1.0) */
+  velocityScale?: number;
+}
+
+/** Projected point result */
+export interface ProjectedPoint {
+  /** Screen X coordinate */
+  x: number;
+  /** Screen Y coordinate */
+  y: number;
+  /** Depth (for sorting) */
+  z: number;
+  /** Scale factor (for size adjustment) */
+  scale: number;
+}
+
+/** Mouse control options */
+export interface MouseControlOptions {
+  /** Invert horizontal rotation */
+  invertX?: boolean;
+  /** Invert vertical rotation */
+  invertY?: boolean;
+}
+
+/** Follow options */
+export interface FollowOptions {
+  /** X offset from target */
+  offsetX?: number;
+  /** Y offset from target */
+  offsetY?: number;
+  /** Z offset from target */
+  offsetZ?: number;
+  /** Auto-orient to look at lookAtTarget */
+  lookAt?: boolean;
+  /** Point to look at (default: origin) */
+  lookAtTarget?: { x: number; y: number; z: number } | null;
+  /** Interpolation speed (0-1, higher = snappier, default: 0.1) */
+  lerp?: number;
+}
+
+/** MoveTo animation options */
+export interface MoveToOptions {
+  /** Target X rotation */
+  rotationX?: number;
+  /** Target Y rotation */
+  rotationY?: number;
+  /** Interpolation speed (0-1, default: 0.05) */
+  lerp?: number;
+}
+
+/**
+ * Camera3D - Pseudo-3D projection and mouse-controlled rotation.
+ * Provides 3D to 2D projection with perspective, rotation controls,
+ * and interactive mouse/touch rotation for 2D canvas applications.
+ *
+ * @example
+ * const camera = new Camera3D({
+ *   rotationX: 0.3,
+ *   rotationY: -0.4,
+ *   perspective: 800,
+ *   inertia: true,
+ *   friction: 0.92
+ * });
+ * camera.enableMouseControl(canvas);
+ *
+ * // In render loop
+ * const { x, y, scale, z } = camera.project(x3d, y3d, z3d);
+ */
+export class Camera3D {
+  /** X rotation in radians */
+  rotationX: number;
+  /** Y rotation in radians */
+  rotationY: number;
+  /** Z rotation in radians */
+  rotationZ: number;
+  /** X position in world space */
+  x: number;
+  /** Y position in world space */
+  y: number;
+  /** Z position in world space */
+  z: number;
+  /** Perspective distance */
+  perspective: number;
+  /** Mouse drag sensitivity */
+  sensitivity: number;
+  /** Minimum X rotation */
+  minRotationX: number;
+  /** Maximum X rotation */
+  maxRotationX: number;
+  /** Whether X rotation is clamped */
+  clampX: boolean;
+  /** Auto-rotation enabled */
+  autoRotate: boolean;
+  /** Auto-rotation speed */
+  autoRotateSpeed: number;
+  /** Auto-rotation axis */
+  autoRotateAxis: 'x' | 'y' | 'z';
+  /** Inertia enabled */
+  inertia: boolean;
+  /** Friction for inertia */
+  friction: number;
+  /** Velocity scale for throws */
+  velocityScale: number;
+
+  constructor(options?: Camera3DOptions);
+
+  /**
+   * Project a 3D point to 2D screen coordinates.
+   * @param x - X coordinate in 3D space
+   * @param y - Y coordinate in 3D space
+   * @param z - Z coordinate in 3D space
+   */
+  project(x: number, y: number, z: number): ProjectedPoint;
+
+  /**
+   * Project multiple points at once.
+   * @param points - Array of 3D points
+   */
+  projectAll(points: Array<{ x: number; y: number; z: number }>): ProjectedPoint[];
+
+  /**
+   * Update camera for auto-rotation, inertia, and follow mode.
+   * @param dt - Delta time in seconds
+   */
+  update(dt: number): void;
+
+  /**
+   * Enable mouse/touch drag rotation on a canvas.
+   * @param canvas - Canvas element to attach controls to
+   * @param options - Control options
+   */
+  enableMouseControl(canvas: HTMLCanvasElement, options?: MouseControlOptions): Camera3D;
+
+  /**
+   * Disable mouse/touch controls.
+   */
+  disableMouseControl(): Camera3D;
+
+  /**
+   * Reset rotation and position to initial values.
+   */
+  reset(): Camera3D;
+
+  /**
+   * Stop any inertia motion immediately.
+   */
+  stopInertia(): Camera3D;
+
+  /**
+   * Set camera position in world space.
+   * @param x - X position
+   * @param y - Y position
+   * @param z - Z position
+   */
+  setPosition(x: number, y: number, z: number): Camera3D;
+
+  /**
+   * Animate camera to a new position.
+   * @param x - Target X position
+   * @param y - Target Y position
+   * @param z - Target Z position
+   * @param options - Animation options
+   */
+  moveTo(x: number, y: number, z: number, options?: MoveToOptions): Camera3D;
+
+  /**
+   * Follow a target object.
+   * @param target - Object with x, y, z properties
+   * @param options - Follow options
+   */
+  follow(target: { x?: number; y?: number; z?: number }, options?: FollowOptions): Camera3D;
+
+  /**
+   * Stop following target.
+   * @param resetPosition - Animate back to initial position
+   */
+  unfollow(resetPosition?: boolean): Camera3D;
+
+  /**
+   * Check if camera is following a target.
+   */
+  isFollowing(): boolean;
+
+  /**
+   * Set rotation angles.
+   * @param x - X rotation in radians
+   * @param y - Y rotation in radians
+   * @param z - Z rotation in radians (optional)
+   */
+  setRotation(x: number, y: number, z?: number): Camera3D;
+
+  /**
+   * Add to current rotation.
+   * @param dx - Delta X rotation
+   * @param dy - Delta Y rotation
+   * @param dz - Delta Z rotation (optional)
+   */
+  rotate(dx: number, dy: number, dz?: number): Camera3D;
+
+  /**
+   * Check if currently being dragged by user.
+   */
+  isDragging(): boolean;
+
+  /**
+   * Look at a specific point.
+   * @param x - Target X in world space
+   * @param y - Target Y in world space
+   * @param z - Target Z in world space
+   */
+  lookAt(x: number, y: number, z: number): Camera3D;
+}
+
+// ==========================================================================
+// IsometricCamera
+// ==========================================================================
+
+/** Options for IsometricCamera */
+export interface IsometricCameraOptions {
+  /** Tile width in pixels (default: 64) */
+  tileWidth?: number;
+  /** Tile height in pixels (default: 32) */
+  tileHeight?: number;
+  /** Camera X offset */
+  offsetX?: number;
+  /** Camera Y offset */
+  offsetY?: number;
+  /** Camera zoom level (default: 1) */
+  zoom?: number;
+  /** Rotation angle (0, 90, 180, 270 degrees) */
+  rotation?: 0 | 90 | 180 | 270;
+}
+
+/**
+ * Isometric camera for 2.5D grid-based projections.
+ * Converts between grid coordinates and screen positions.
+ *
+ * @example
+ * const camera = new IsometricCamera({
+ *   tileWidth: 64,
+ *   tileHeight: 32,
+ *   offsetX: 400,
+ *   offsetY: 100
+ * });
+ *
+ * const screen = camera.gridToScreen(5, 3);
+ * const grid = camera.screenToGrid(mouseX, mouseY);
+ */
+export class IsometricCamera {
+  /** Tile width in pixels */
+  tileWidth: number;
+  /** Tile height in pixels */
+  tileHeight: number;
+  /** Camera X offset */
+  offsetX: number;
+  /** Camera Y offset */
+  offsetY: number;
+  /** Camera zoom level */
+  zoom: number;
+  /** Camera rotation (0, 90, 180, 270) */
+  rotation: 0 | 90 | 180 | 270;
+
+  constructor(options?: IsometricCameraOptions);
+
+  /**
+   * Convert grid coordinates to screen position.
+   * @param gridX - Grid X coordinate
+   * @param gridY - Grid Y coordinate
+   * @param height - Optional height offset
+   */
+  gridToScreen(gridX: number, gridY: number, height?: number): { x: number; y: number };
+
+  /**
+   * Convert screen position to grid coordinates.
+   * @param screenX - Screen X coordinate
+   * @param screenY - Screen Y coordinate
+   */
+  screenToGrid(screenX: number, screenY: number): { x: number; y: number };
+
+  /**
+   * Rotate camera by 90 degrees.
+   * @param clockwise - Rotate clockwise (default: true)
+   */
+  rotate90(clockwise?: boolean): void;
+
+  /**
+   * Set camera offset.
+   * @param x - X offset
+   * @param y - Y offset
+   */
+  setOffset(x: number, y: number): void;
+
+  /**
+   * Set zoom level.
+   * @param zoom - Zoom multiplier
+   */
+  setZoom(zoom: number): void;
+
+  /**
+   * Pan camera by delta.
+   * @param dx - X delta
+   * @param dy - Y delta
+   */
+  pan(dx: number, dy: number): void;
+
+  /**
+   * Center camera on grid position.
+   * @param gridX - Grid X coordinate
+   * @param gridY - Grid Y coordinate
+   * @param screenWidth - Screen width
+   * @param screenHeight - Screen height
+   */
+  centerOn(gridX: number, gridY: number, screenWidth: number, screenHeight: number): void;
+}

package/types/webgl.d.ts

@@ -0,0 +1,109 @@
+/**
+ * GCanvas WebGL Module
+ * Optional WebGL rendering capabilities for enhanced visual effects.
+ * @module webgl
+ */
+
+// ==========================================================================
+// WebGL Renderer
+// ==========================================================================
+
+/** WebGL renderer options */
+export interface WebGLRendererOptions {
+  /** Canvas element */
+  canvas: HTMLCanvasElement;
+  /** Whether to preserve drawing buffer */
+  preserveDrawingBuffer?: boolean;
+  /** Enable antialiasing */
+  antialias?: boolean;
+  /** Enable alpha blending */
+  alpha?: boolean;
+  /** Enable depth testing */
+  depth?: boolean;
+  /** Enable stencil buffer */
+  stencil?: boolean;
+  /** Premultiplied alpha */
+  premultipliedAlpha?: boolean;
+}
+
+/**
+ * WebGL renderer for enhanced visual effects.
+ * Provides shader-based rendering for complex effects.
+ */
+export class WebGLRenderer {
+  /** WebGL rendering context */
+  readonly gl: WebGLRenderingContext | WebGL2RenderingContext;
+  /** Canvas element */
+  readonly canvas: HTMLCanvasElement;
+  /** Whether WebGL is available */
+  readonly isAvailable: boolean;
+
+  constructor(options: WebGLRendererOptions);
+
+  /**
+   * Create and compile a shader program.
+   * @param vertexSource - Vertex shader GLSL source
+   * @param fragmentSource - Fragment shader GLSL source
+   * @returns Compiled shader program
+   */
+  createProgram(vertexSource: string, fragmentSource: string): WebGLProgram;
+
+  /**
+   * Set uniform value.
+   * @param program - Shader program
+   * @param name - Uniform name
+   * @param value - Uniform value
+   */
+  setUniform(program: WebGLProgram, name: string, value: number | number[] | Float32Array): void;
+
+  /**
+   * Create a texture from an image or canvas.
+   * @param source - Image or canvas source
+   * @returns WebGL texture
+   */
+  createTexture(source: HTMLImageElement | HTMLCanvasElement | ImageData): WebGLTexture;
+
+  /**
+   * Render a full-screen quad with a shader.
+   * @param program - Shader program to use
+   */
+  renderFullscreenQuad(program: WebGLProgram): void;
+
+  /**
+   * Clear the canvas.
+   * @param r - Red (0-1)
+   * @param g - Green (0-1)
+   * @param b - Blue (0-1)
+   * @param a - Alpha (0-1)
+   */
+  clear(r?: number, g?: number, b?: number, a?: number): void;
+
+  /**
+   * Resize the renderer to match canvas size.
+   */
+  resize(): void;
+
+  /**
+   * Dispose of WebGL resources.
+   */
+  dispose(): void;
+}
+
+// ==========================================================================
+// Shader Collections
+// ==========================================================================
+
+/**
+ * Pre-built shaders for 3D sphere rendering.
+ */
+export namespace SPHERE_SHADERS {
+  /** Basic sphere vertex shader */
+  const vertex: string;
+  /** Basic sphere fragment shader with lighting */
+  const fragment: string;
+  /** Glow effect fragment shader */
+  const glowFragment: string;
+  /** Atmosphere effect fragment shader */
+  const atmosphereFragment: string;
+}
+