Documentation / @ripl/vue-3d

@ripl/vue-3d

Declarative Vue 3 components for Ripl 3D scenes.

A 3D context is an ordinary Ripl context and a 3D shape is an ordinary element, so this package adds only what 3D genuinely needs: a context, nine shapes, a group, a camera and five lights. The scene, renderer and transition components from @ripl/vue drive a 3D scene unchanged.

Installation

npm install @ripl/vue-3d

@ripl/vue arrives as a dependency. vue (3.5 or later) is a peer dependency.

Quick start

import {
    createRipl3D,
} from '@ripl/vue-3d';

createApp(App).use(createRipl3D()).mount('#app');

createRipl3D() registers the core Ripl components too. Applying createRipl() as well is harmless in either order.

<template>
    <ripl-context-3d :lights="lights">
        <ripl-scene>
            <ripl-renderer :auto-stop="false">
                <ripl-camera :position="[0, 2, 5]" :interactions="true" />

                <ripl-group-3d :rotation-y="spin">
                    <ripl-cube :size="1" :x="-1" fill="#4488ff" />
                    <ripl-sphere :radius="0.6" :x="1" fill="#ff006e" />
                </ripl-group-3d>
            </ripl-renderer>
        </ripl-scene>
    </ripl-context-3d>
</template>

auto-stop="false" is the norm in 3D: camera and light changes ask the context to repaint rather than changing element state, so a renderer that idles when no transition is running would stop before they land.

Components

Component	Wraps
<ripl-context-3d>	createContext from @ripl/3d
<ripl-cube>, <ripl-sphere>, <ripl-cylinder>, <ripl-cone>, <ripl-plane>, <ripl-torus>	the primitive shapes
<ripl-mesh>, <ripl-parametric>, <ripl-bezier-surface>	the geometry-driven shapes
<ripl-group-3d>	createGroup3D
<ripl-camera>	createCamera
<ripl-ambient-light>, <ripl-hemisphere-light>, <ripl-directional-light>, <ripl-point-light>, <ripl-spot-light>	the light factories

Compositions

import {
    useRiplCamera,
    useRiplContext3D,
} from '@ripl/vue-3d';

const context = useRiplContext3D();
const camera = useRiplCamera();

The four core compositions are re-exported, so one import covers a whole scene.

Notes

• There is no zIndex on a 3D shape: it derives depth ordering from its projected position.
• A group's transform lives outside element state, so it applies immediately and cannot be animated by a <ripl-transition>. Animate the children instead.
• A context resolves at most eight lights. Binding the context's lights prop, even to [], is what clears the default ambient-plus-directional rig.

Documentation

Full documentation lives at ripl.run.

License

MIT

Interfaces

Interface	Description
RiplCameraProps	Props accepted by RiplCamera.
RiplContext3DProps	Props accepted by RiplContext3D.
RiplDirectionalLightProps	Props accepted by RiplDirectionalLight.
RiplGroup3DProps	Props accepted by RiplGroup3D.
RiplHemisphereLightProps	Props accepted by RiplHemisphereLight.
RiplLightProps	Props shared by every light component.
RiplPointLightProps	Props accepted by RiplPointLight.
RiplSpotLightProps	Props accepted by RiplSpotLight.

Type Aliases

Type Alias	Description
Ripl3DBaseState	The state every 3D shape carries, minus zIndex — a 3D shape derives that from projected depth and ignores an assigned value.
Ripl3DElementProps	The full prop surface of a 3D shape component: the shape's own state, the shared construction options and paint flags, and its event listeners.

Variables

Variable	Description
BASE_3D_STATE_KEYS	The base state a 3D shape inherits, minus zIndex.
GROUP_3D_FIELD_KEYS	The transform a group applies to its subtree.
RIPL_CAMERA	Injection key for the camera viewing the enclosing 3D context.
RIPL_CONTEXT_3D	Injection key for the 3D rendering context the subtree draws to.
RiplAmbientLight	Lights every surface equally, regardless of orientation.
RiplBezierSurface	A surface tessellated from one or more bicubic Bézier patches.
RiplCamera	Views the enclosing 3D context, optionally with pointer orbit, pan and zoom.
RiplCone	A cone rising from a circular base.
RiplContext3D	Creates a Ripl 3D rendering context and provides it to its subtree, mounting the canvas into its own root element.
RiplCube	A cube with uniform edge length.
RiplCylinder	A cylinder, or a truncated cone when its two cap radii differ.
RiplDirectionalLight	Lights every surface from one direction, as a distant source does.
RiplGroup3D	Groups its children, composing its transform onto theirs and cascading its state to them.
RiplHemisphereLight	Lights surfaces from above with one colour and from below with another.
RiplMesh	An arbitrary mesh built from an explicit face list.
RiplParametric	A surface tessellated from a parametric function of two variables.
RiplPlane	A flat rectangle in the XY plane.
RiplPointLight	Lights outwards from a point in space, falling off with distance.
RiplRenderer	Drives the enclosing scene with a requestAnimationFrame loop, and makes transitions available to its subtree.
RiplScene	Creates a scene bound to the enclosing context and parents its subtree to it.
RiplSphere	A sphere, tessellated into longitudinal segments and latitudinal rings.
RiplSpotLight	Lights a cone from a point in space, with a soft or hard edge.
RiplTorus	A torus: a tube swept around a major ring.
RiplTransition	Animates the descendants it wraps as they enter, update and leave, mirroring Vue's own enter-from / leave-to model.
SHAPE_3D_FIELD_KEYS	Plain fields on a 3D shape, written through an accessor rather than the state bag.
SHAPE_3D_FIELDS	Fields that change how a 3D shape paints, so a repaint has to be requested when they change.
SHAPE_3D_KEYS	The state properties specific to each built-in 3D shape, keyed by shape type.
SHAPE_3D_STATE_KEYS	The transform and surface state every 3D shape adds on top of the shared base state.

Functions

Function	Description
createRipl3D	Creates the Vue plugin that registers every Ripl 3D component globally, along with the core components from @ripl/vue that a 3D scene needs — <ripl-scene>, <ripl-renderer> and <ripl-transition>.
useRiplCamera	Returns the camera provided by the nearest <ripl-camera>.
useRiplContext	Returns the rendering context provided by the nearest context component.
useRiplContext3D	Returns the 3D rendering context provided by the nearest <ripl-context-3d>.
useRiplElement	Returns the nearest enclosing element, group or scene.
useRiplRenderer	Returns the renderer provided by the nearest renderer component.
useRiplScene	Returns the scene provided by the nearest scene component.