useTresContext

useTresContext provides a complete access to the TresJS context.

The useTresContext composable provides complete access to the full TresJS context with all internal management systems, including advanced camera management, renderer control, and event handling. It's designed for advanced use cases where you need direct access to all TresJS internals.

Usage

useTresContext can only be used in child components of a TresCanvas component, as its data is provided by TresCanvas.

import { useTresContext } from '@tresjs/core'

const { scene, renderer, camera, sizes, events } = useTresContext()

// Access the camera management system
console.log('Active camera:', camera.activeCamera.value)
console.log('All cameras:', camera.cameras.value)

// Access the complete renderer manager
console.log('Render mode:', renderer.mode)
console.log('Can invalidate:', renderer.canBeInvalidated.value)

// Register a new camera
const myCamera = new PerspectiveCamera(75, 1, 0.1, 1000)
camera.registerCamera(myCamera, true) // Set as active

Advanced Camera Management

<script setup lang="ts">
import { useTresContext } from '@tresjs/core'
import { OrthographicCamera, PerspectiveCamera } from 'three'
import { ref } from 'vue'

const { camera, sizes } = useTresContext()

const isPerspective = ref(true)

const switchCameraType = () => {
  const currentPos = camera.activeCamera.value?.position.clone()

  // Remove current cameras
  camera.cameras.value.forEach(cam => camera.deregisterCamera(cam))

  if (isPerspective.value) {
    // Switch to orthographic
    const orthoCam = new OrthographicCamera(-10, 10, 10, -10, 0.1, 1000)
    if (currentPos) {
      orthoCam.position.copy(currentPos)
      orthoCam.lookAt(0, 0, 0)
    }
    camera.registerCamera(orthoCam, true)
  }
  else {
    // Switch to perspective
    const perspCam = new PerspectiveCamera(75, sizes.aspectRatio.value, 0.1, 1000)
    if (currentPos) {
      perspCam.position.copy(currentPos)
      perspCam.lookAt(0, 0, 0)
    }
    camera.registerCamera(perspCam, true)
  }

  isPerspective.value = !isPerspective.value
}
</script>

<template>
  <TresMesh @click="switchCameraType">
    <TresBoxGeometry />
    <TresMeshNormalMaterial />
  </TresMesh>
</template>

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import CameraController from './CameraController.vue'
</script>

<template>
  <TresCanvas>
    <CameraController />
  </TresCanvas>
</template>

Advanced Renderer Control

Use the full renderer manager for sophisticated rendering control:

<script setup lang="ts">
import { useTresContext } from '@tresjs/core'
import { watchEffect } from 'vue'

const { renderer, sizes } = useTresContext()

// Access advanced renderer properties
watchEffect(() => {
  console.log('Render mode:', renderer.mode)
  console.log('Can be invalidated:', renderer.canBeInvalidated.value)
  console.log('Render loop active:', renderer.loop.isActive.value)
})

// Register custom render callbacks
renderer.onRender((rendererInstance) => {
  console.log('Frame rendered with:', rendererInstance)
})

renderer.onReady((rendererInstance) => {
  console.log('Renderer ready:', rendererInstance)
  // Setup custom post-processing here
})

// Advanced frame control
const triggerMultipleFrames = () => {
  // Invalidate with custom frame count with on-demand mode
  renderer.invalidate(5) // Render next 5 frames
}
</script>

Event System Integration

Access the complete event management system:

<script setup lang="ts">
import { useTresContext } from '@tresjs/core'

const { events } = useTresContext()

// Handle global pointer missed events
events.onPointerMissed((event) => {
  console.log('Clicked on empty space:', event)
  // Deselect objects, close menus, etc.
})
</script>

Custom Renderer Setup

For complete control over renderer initialization:

<script setup lang="ts">
import { useTresContext } from '@tresjs/core'
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer'
import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass'

const { renderer, scene, camera } = useTresContext()

// Access the raw renderer instance
const rawRenderer = renderer.instance

// Setup advanced post-processing pipeline
const composer = new EffectComposer(rawRenderer)
const renderPass = new RenderPass(scene.value, camera.activeCamera.value!)
composer.addPass(renderPass)

// Take over the render function
renderer.replaceRenderFunction((notifyComplete) => {
  composer.render()
  notifyComplete()
})
</script>

Properties

The useTresContext composable returns the complete TresJS context with the following properties:

scene

ShallowRef<TresScene>

The Three.js scene object containing all 3D objects in your scene.

sizes

SizesType

Reactive size information including canvas width, height, aspect ratio, and pixel ratio.

extend

(objects: any) => void

Function to extend the TresJS component catalogue with custom Three.js objects.

camera

UseCameraReturn

Complete camera management system with registration, deregistration, and active camera control.

controls

Ref<TresControl | null>

Reference to the current camera controls instance (e.g., OrbitControls, FlyControls).

renderer

UseRendererManagerReturn

Complete renderer management system with advanced rendering control, frame management, and event hooks.

events

EventManager

Complete event management system for handling pointer interactions and global events.

Camera Management System (`camera`)

activeCamera

ComputedRef<TresCamera>

The currently active camera in the scene. Always guaranteed to exist.

cameras

Ref<TresCamera[]>

Array of all registered cameras in the scene.

registerCamera

(camera: TresCamera, active?: boolean) => void

deregisterCamera

(camera: TresCamera) => void

Remove a camera from the scene management system.

setActiveCamera

(cameraOrUuid: string | TresCamera) => void

Set a specific camera as the active one using camera instance or UUID.

Renderer Management System (`renderer`)

instance

TresRenderer

The raw Three.js WebGL renderer instance.

loop

RafLoop

The render loop system with start, stop, and event hooks.

advance

() => void

Manually advance one frame in manual render mode.

invalidate

(frames?: number) => void

Mark the scene for re-rendering in on-demand mode. Optional frame count parameter.

canBeInvalidated

ComputedRef<boolean>

Whether the renderer can currently be invalidated (on-demand mode only).

mode

RenderMode

Current render mode: 'always', 'on-demand', or 'manual'.

onReady

(callback: (renderer: TresRenderer) => void) => void

onRender

(callback: (renderer: TresRenderer) => void) => void

replaceRenderFunction

(fn: RenderFunction) => void

Take complete control over the rendering process with a custom render function.

Difference from useTres

useTresContext provides complete access to all TresJS internals compared to the simplified useTres interface.

Feature	useTresContext	useTres
Renderer	Complete renderer manager with advanced controls	Direct renderer instance only
Camera	Full camera management system with registration/switching	Active camera reference only
Complexity	Complete internal access, all management features	Simplified, focused API
Use Case	Advanced scenarios, plugin development, internal operations	Most common 3D scene interactions
Performance Control	Fine-grained frame control, custom render functions	Basic invalidate/advance only
Event Handling	Complete event management system	Basic event manager access

Developer Tip: Choose useTresContext for advanced 3D applications, plugin development, or when you need complete control over the rendering pipeline. Use useTres for typical 3D scene interactions.

Type

Signature

function useTresContext(): TresContext

interface TresContext {
  /** The Three.js scene object containing all 3D objects */
  scene: ShallowRef<TresScene>
  /** Reactive size information for the canvas */
  sizes: SizesType
  /** TresJS extension function for adding custom objects */
  extend: (objects: any) => void
  /** Complete camera management system */
  camera: UseCameraReturn
  /** Reference to current camera controls */
  controls: Ref<TresControl | null>
  /** Complete renderer management system */
  renderer: UseRendererManagerReturn
  /** Complete event management system */
  events: EventManager
}

interface UseCameraReturn {
  /** The currently active camera */
  activeCamera: ComputedRef<TresCamera>
  /** Array of all registered cameras */
  cameras: Ref<TresCamera[]>
  /** Register a new camera */
  registerCamera: (camera: TresCamera, active?: boolean) => void
  /** Remove a camera from management */
  deregisterCamera: (camera: TresCamera) => void
  /** Set a specific camera as active */
  setActiveCamera: (cameraOrUuid: string | TresCamera) => void
}

interface UseRendererManagerReturn {
  /** The render loop system */
  loop: RafLoop
  /** The raw Three.js renderer instance */
  instance: TresRenderer
  /** Manually advance one frame (manual mode) */
  advance: () => void
  /** Register callback for renderer ready event */
  onReady: (callback: (renderer: TresRenderer) => void) => void
  /** Register callback for after render event */
  onRender: (callback: (renderer: TresRenderer) => void) => void
  /** Mark scene for re-render (on-demand mode) */
  invalidate: (frames?: number) => void
  /** Whether renderer can be invalidated */
  canBeInvalidated: ComputedRef<boolean>
  /** Current render mode */
  mode: RenderMode
  /** Take control of render function */
  replaceRenderFunction: (fn: RenderFunction) => void
}

interface SizesType {
  /** Canvas width in pixels */
  width: Ref<number>
  /** Canvas height in pixels */
  height: Ref<number>
  /** Canvas aspect ratio (width / height) */
  aspectRatio: Ref<number>
  /** Device pixel ratio */
  pixelRatio: Ref<number>
}

type RenderMode = 'always' | 'on-demand' | 'manual'
type RenderFunction = (notifySuccess: () => void) => void
type TresRenderer = WebGLRenderer | Renderer
type TresCamera = Camera

useTres

useTres provides a convenient access to a simplified TresJS context.

useLoop

useLoop provides a convenient access to the render loop of the TresJS scene.