Tresjs/docs/content/3.api/2.composables/2.use-tres-context.md

---

title: useTresContext

description: 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

::warning 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

::code-group

<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:

:::field-group ::::field{name="scene" type="ShallowRef"} The Three.js scene object containing all 3D objects in your scene. ::::

::::field{name="sizes" type="SizesType"} Reactive size information including canvas width, height, aspect ratio, and pixel ratio. ::::

::::field{name="extend" type="(objects: any) => void"} Function to extend the TresJS component catalogue with custom Three.js objects. ::::

::::field{name="camera" type="UseCameraReturn"} Complete camera management system with registration, deregistration, and active camera control. ::::

::::field{name="controls" type="Ref"} Reference to the current camera controls instance (e.g., OrbitControls, FlyControls). ::::

::::field{name="renderer" type="UseRendererManagerReturn"} Complete renderer management system with advanced rendering control, frame management, and event hooks. ::::

::::field{name="events" type="EventManager"} Complete event management system for handling pointer interactions and global events. :::: :::

Camera Management System (camera)

:::field-group ::::field{name="activeCamera" type="ComputedRef"} The currently active camera in the scene. Always guaranteed to exist. ::::

::::field{name="cameras" type="Ref"} Array of all registered cameras in the scene. ::::

::::field{name="registerCamera" type="(camera: TresCamera, active?: boolean) => void"} Register a new camera in the scene. Optionally set it as the active camera. ::::

::::field{name="deregisterCamera" type="(camera: TresCamera) => void"} Remove a camera from the scene management system. ::::

::::field{name="setActiveCamera" type="(cameraOrUuid: string | TresCamera) => void"} Set a specific camera as the active one using camera instance or UUID. :::: :::

Renderer Management System (renderer)

:::field-group ::::field{name="instance" type="TresRenderer"} The raw Three.js WebGL renderer instance. ::::

::::field{name="loop" type="RafLoop"} The render loop system with start, stop, and event hooks. ::::

::::field{name="advance" type="() => void"} Manually advance one frame in manual render mode. ::::

::::field{name="invalidate" type="(frames?: number) => void"} Mark the scene for re-rendering in on-demand mode. Optional frame count parameter. ::::

::::field{name="canBeInvalidated" type="ComputedRef"} Whether the renderer can currently be invalidated (on-demand mode only). ::::

::::field{name="mode" type="RenderMode"} Current render mode: 'always', 'on-demand', or 'manual'. ::::

::::field{name="onReady" type="(callback: (renderer: TresRenderer) => void) => void"} Register a callback for when the renderer is fully initialized. ::::

::::field{name="onRender" type="(callback: (renderer: TresRenderer) => void) => void"} Register a callback that fires after each frame is rendered. ::::

::::field{name="replaceRenderFunction" type="(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

::tip 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

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