feat: 633 use loop

[alvarosabu]

Hopefully Closes #633

Based on the team discussion. This PR introduces a new API

useLoop

This composable allows you to execute a callback on every frame, similar to useRenderLoop but unique to each TresCanvas instance and with access to the context.

Warning

useLoop can only be used inside of a TresCanvas since this component acts as the provider for the context data.

Usage

Register update callbacks

The user can register update callbacks (such as animations, fbo, etc) using the onBeforeRender

<script setup>
import { useLoop } from '@tresjs/core'

const boxRef = ref()

const { onBeforeRender } = useLoop()

onBeforeRender(({ delta }) => {
  boxRef.value.rotation.y += delta
})
</script>

Take over the render loop

The user can take over the render loop callback by using the render method

const { render } = useLoop()

render(({ renderer, scene, camera }) => {
  renderer.render(scene, camera)
})

Note

To run this example please run the playground and go to http://localhost:5173/advanced/take-over-loop

Register after render callbacks (ex physics calculations)

The user can also register after rendering callbacks using the onAfterRender

const { onAfterRender } = useLoop()

onAfterRender(({ renderer }) => {
  // Calculations
})

Priority mechanism

Both useBeforeRender and useAfteRender provide an optional priority index. This indexes could be any from [Number.NEGATIVE_INFINITY ... 0 ... Number.NEGATIVE_INFINITY]

const { onBeforeRender, pause, resume } = useLoop()

onBeforeRender((state) => {
  if (!sphereRef.value) { return }
  console.log('updating sphere')
  sphereRef.value.position.y += Math.sin(state.elapsed) * 0.01
})

onBeforeRender(() => {
   console.log('this should happen before updating the sphere')
}, -1)

For example, to use Frame Object Buffer (FBO) is convenient to use a very big number to ensure that all updates happen before the FBO callback and the last one just before the scene render.

Note

To run this example (FBO) please run the playground and go to http://localhost:5173/advanced/fbo`

Pausing and resuming the loop

The end user can use pause and resume methods:

const { onBeforeRender, pause, resume } = useLoop()

onBeforeRender(({ elapse }) => {
  sphereRef.value.position.y += Math.sin(elapsed) * 0.01
})

pause() // This stops the clock, delta = 0 and freezes elapsed.

Pausing and resuming the render

You can use pauseRender and resumeRender methods:

const { pauseRender, resumeRender } = useLoop()

onBeforeRender(({ elapse }) => {
  sphereRef.value.position.y += Math.sin(elapsed) * 0.01
})

pauseRender() // This will pause the renderer
resumeRender() // This will resume the renderer

Pending

• Tests
• Documentation

[JaimeTorrealba]

I don't see problems, thanks for this big work Alvaro

[andretchen0]

I agree with @Tinoooo . off should be documented. on and trigger shouldn't be returned.

[alvarosabu]

I agree with @Tinoooo . off should be documented. on and trigger shouldn't be returned.

Awesome @andretchen0 , I already made the changes on the return and documented the off method

[Tinoooo]

suggestion: I suggest creating a method that creates this method to avoid code duplication like mentioned here

[Tinoooo]

question: Can this be moved to useRenderer? This would be beneficial for the seperation of concerns and the dependencies would be more obvious.

[andretchen0]

Ah, I had commented the opposite.

Making this case for that:

If we move the question "should the scene be rendered?" to useRenderer that means:

• useRenderer has to be passed render, invalidate, advance, and renderMode – 4 dependencies it otherwise doesn't require
• it has to know and implement the update policies, which are orthogonal to what WebGLRenderer otherwise does.

If we want to keep the update in useRenderer, I think it'd be better off encapulated in a single dependency like onRender() – which it would simply call. But I'd personally prefer that it be removed from useRenderer altogether. The render policy can be part of the loop:

if (renderPolicy.shouldRender()) {
    renderer.render()
}

In this way, we eliminate the dependencies in useRenderer altogether and put them behind an interface – nothing else needs to muck around with the implementation.

[alvarosabu]

I already moved it.... can we please agree on one way @Tinoooo @andretchen0 ?

[andretchen0]

@alvarosabu

I'd prefer to reduce dependencies in useRenderer, but I won't block the PR because of it. It's your call.

[Tinoooo]

question: Can/Should we make sure that this is resored once a user replaced the rendering with a custom callback and removed it afterwards via off?

[andretchen0]

Does this work? I'm getting

Error: useTresContext must be used together with useTresContextProvider

vAlwaysLookAt only runs if updated – I think that's a bug – so you'll have to update it in order to get the error to throw.

<script setup lang="ts">
import { shallowRef } from 'vue'
import { vAlwaysLookAt, vLightHelper } from '@tresjs/core'

const other = shallowRef([1,1,1])

setTimeout(() => other.value = [2,1,1], 1000)
</script>

<template>
  <TresDirectionalLight v-light-helper v-always-look-at="other" :position="[3, 3, 3]" :intensity="1" />
</template>

[alvarosabu]

I'm gonna remove the directives with loop. They are not adding enough value for the troubles

[andretchen0]

If possible, it's probably be best to avoid wrapping the callback.

Currently, for every callback function in every frame, this code is recreating the argument object.

The argument object only needs to be created once.

[alvarosabu]

@andretchen0 how do we get the latest context if we are returning the plain values? if we called once on the onLoop is only going to return the snapshot of the context at that specific moment.

[andretchen0]

For separation of concerns, I'd move this somewhere else.

Almost all core code has access to the renderer, so this could live just about anywhere.

On the other hand, useRenderer has to be passed render, loop, invalidate, advance, in order to do loop.register.

[andretchen0]

This can't be offed.

playground/src/components/TakeOverLoopExperience.vue

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

import { OrbitControls } from '@tresjs/cientos'
import { useControls } from '@tresjs/leches'

const { render, pauseRender, resumeRender } = useLoop()

const off = render(({ renderer, scene, camera }) => {
  console.log('on')
  renderer.render(scene, camera)
}).off

setTimeout(() => {off(); console.log('offing')}, 1000)

const { isRenderPaused } = useControls({
  isRenderPaused: {
    value: false,
    type: 'boolean',
    label: 'Pause Render',
  },
})

watchEffect(() => {
  if (isRenderPaused.value) {
    pauseRender()
  }
  else {
    resumeRender()
  }
})
</script>

<template>
  <TresPerspectiveCamera :position="[3, 3, 3]" />
  <OrbitControls />
  <AnimatedObjectUseUpdate />
  <TresAmbientLight :intensity="1" /> />
  <TresGridHelper />
</template>

[alvarosabu]

Hey @andretchen0 please check the discord discussion