# google-three

Three.js WebGL overlay view factory for Google Maps.

---

## `getWebGLOverlayViewClass(WebGLOverlayView)`

Returns a subclass of the given `google.maps.WebGLOverlayView` constructor that integrates a Three.js scene with Google Maps WebGL rendering.

Call this once after the Google Maps API has loaded, passing `google.maps.WebGLOverlayView`. The returned class can be instantiated with an anchor coordinate to position the Three.js scene on the map.

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `WebGLOverlayView` | `typeof google.maps.WebGLOverlayView` | The base class from the loaded Google Maps API |

### Returns

`new (anchor: google.maps.LatLng | google.maps.LatLngLiteral) => IWebGLOverlayView` — A constructor for the overlay view class.

### Example

```typescript
import { getWebGLOverlayViewClass } from '@yaoc1996/js-tools/google'

const WebGLOverlayViewClass = getWebGLOverlayViewClass(google.maps.WebGLOverlayView)

const overlay = new WebGLOverlayViewClass({ lat: 37.7749, lng: -122.4194 })
overlay.setMap(map)
```

---

## `IWebGLOverlayView`

Interface implemented by the class returned from `getWebGLOverlayViewClass`. Extends `google.maps.WebGLOverlayView`.

### Members

#### `anchor`

`google.maps.LatLng` — The anchor coordinate passed to the constructor.

#### `worldAnchor`

`[number, number, number]` — The anchor converted to EPSG:3857 world coordinates `[x, y, altitude]`.

#### `add(...args)`

Forwards to the internal `THREE.Scene.add()`. Adds objects to the scene.

#### `remove(...args)`

Forwards to the internal `THREE.Scene.remove()`. Removes objects from the scene.

#### `addRenderEventListener(type, cb)`

Registers a listener for render lifecycle events.

| Name | Type | Description |
|------|------|-------------|
| `type` | `keyof CustomLayerEventMap` | Event name: `'add'`, `'remove'`, `'beforerender'`, or `'afterrender'` |
| `cb` | `EventListener<CustomLayerEventMap, EventType>` | Callback receiving the event payload |

Returns `() => void` — a cleanup function that removes the listener.

#### `removeRenderEventListener(type, cb)`

Removes a previously registered listener.

| Name | Type | Description |
|------|------|-------------|
| `type` | `keyof CustomLayerEventMap` | Event name |
| `cb` | `EventListener<CustomLayerEventMap, EventType>` | The same callback reference passed to `addRenderEventListener` |

#### `dispose()`

Disposes the internal `WebGLRenderer` and releases GPU resources. Safe to call when no renderer is active.

---

## Types

```typescript
type CustomLayerEventMap = {
    add: {
        renderer: WebGLRenderer;
    };
    remove: {
        renderer: WebGLRenderer;
    };
    beforerender: {
        renderer: WebGLRenderer;
        scene: Scene;
        camera: Camera;
    };
    afterrender: {
        renderer: WebGLRenderer;
        scene: Scene;
        camera: Camera;
    };
};
```
