Skip to content

Commit 5b81e59

Browse files
committed
readme
1 parent 02fd9f1 commit 5b81e59

File tree

3 files changed

+61
-101
lines changed

3 files changed

+61
-101
lines changed

libs/soba/misc/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This secondary entry point includes miscellaneous utilities and components for a
88
- [injectFBO](#injectfbo)
99
- [NgtsFBO](#ngtsfbo)
1010
- [NgtsBakeShadows](#ngtsbakeshadows)
11+
- [injectDepthBuffer](#injectdepthbuffer)
1112

1213
## `injectAnimations`
1314

@@ -86,3 +87,18 @@ A directive that bakes shadows in your scene. It sets `gl.shadowMap.autoUpdate`
8687
```html
8788
<ngts-bake-shadows />
8889
```
90+
91+
## injectDepthBuffer
92+
93+
Renders the scene into a depth-buffer. Often effects depend on it and this allows you to render a single buffer and share it, which minimizes the performance impact. It returns the buffer's `depthTexture`.
94+
95+
Since this is a rather expensive effect you can limit the amount of frames it renders when your objects are static. For instance making it render only once by setting `frames: 1`.
96+
97+
```ts
98+
export class MyCmp {
99+
depthBuffer = injectDepthBuffer(() => ({
100+
size: 256, // The size of the depth buffer
101+
frames: Infinity, // The amount of frames to render
102+
}));
103+
}
104+
```

libs/soba/misc/src/lib/depth-buffer.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
import { computed, Injector } from '@angular/core';
22
import { injectBeforeRender, injectStore, pick } from 'angular-three';
3-
import { injectFBO } from 'angular-three-soba/misc';
43
import { assertInjector } from 'ngxtension/assert-injector';
54
import { DepthFormat, DepthTexture, UnsignedShortType } from 'three';
5+
import { injectFBO } from './fbo';
66

77
export function injectDepthBuffer(
88
params: () => { size?: number; frames?: number } = () => ({}),

libs/soba/staging/README.md

Lines changed: 44 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ npm install @pmndrs/vanilla @monogrid/gainmap-js
2525
- [NgtsBounds](#ngtsbounds)
2626
- [NgtsStage](#ngtsstage)
2727
- [NgtsCaustics](#ngtscaustics)
28+
- [NgtsSky](#ngtssky)
29+
- [NgtsSpotLight](#ngtsspotlight)
30+
- [NgtsSpotLightShadow](#ngtsspotlightshadow)
2831

2932
## NgtsAccumulativeShadows
3033

@@ -393,118 +396,59 @@ Calculates a boundary box and centers the camera accordingly. If you are using c
393396

394397
### Object Inputs (NgtsBoundsOptions)
395398

396-
| Property | Description | Default Value |
397-
| ----------------- | -------------------------------------------- | ------------- |
398-
| `fit` | Fits the current view on first render. | false |
399-
| `clip` | Sets the cameras near/far planes. | false |
400-
| `observe` | Triggers on window resize. | false |
401-
| `maxDuration` | The animation length in seconds. | 1 |
402-
| `interpolateFunc` | Defines how the animation changes over time. | default |
399+
| Property | Description | Default Value |
400+
| ------------- | -------------------------------------- | ------------- |
401+
| `fit` | Fits the current view on first render. | false |
402+
| `clip` | Sets the cameras near/far planes. | false |
403+
| `observe` | Triggers on window resize. | false |
404+
| `maxDuration` | The animation length in seconds. | 1 |
403405

404-
```html
405-
<ngts-bounds [options]="{ fit: true, clip: true, observe: true, maxDuration: 1, }">
406-
<ngt-mesh />
407-
</ngts-bounds>
408-
```
409-
410-
`NgtsBounds` component also acts as a service **for its children**. Inject `NgtsBounds` to refresh the bounds, fit the camera, clip near/far planes, go to camera orientations or focus objects. `refresh(object?: THREE.Object3D | THREE.Box3)` will recalculate bounds, since this can be expensive only call it when you know the view has changed. `reset` centers the view. `moveTo` changes the camera position. `lookAt` changes the camera orientation, with the respect to up-vector, if specified. `clip` sets the cameras near/far planes. `fit` centers the view for non-orthographic cameras (same as reset) or zooms the view for orthographic cameras.
411-
412-
```ts
413-
const bounds = inject(NgtsBounds);
414-
415-
bounds.refresh();
416-
bounds.reset();
417-
bounds.moveTo(new Vector3(0, 0, 0));
418-
bounds.lookAt(new Vector3(0, 0, 0), new Vector3(0, 1, 0));
419-
bounds.clip();
420-
bounds.fit();
421-
```
422-
423-
## NgtsStage
424-
425-
A component that creates a "stage" with proper studio lighting, 0/0/0 top-centred, model-shadows, ground-shadows and optional zoom to fit. Make sure to set `makeDefault` on your controls when `adjustCamera` is true!
426-
427-
### Object Inputs (NgtsStageOptions)
428-
429-
| Property | Description | Default Value |
430-
| -------------- | ----------------------------------------------------------------------------------------------- | ------------- |
431-
| `preset` | Lighting setup. | 'rembrandt' |
432-
| `shadows` | Controls the ground shadows. Can be `'contact'`, `'accumulative'`, or `NgtsStageShadowsOptions` | 'contact' |
433-
| `adjustCamera` | Optionally wraps and centers the models using <Bounds>, can also be a margin. | true |
434-
| `environment` | The default environment. | 'city' |
435-
| `intensity` | The lighting intensity. | 0.5 |
436-
| `center` | To adjust centering. | |
437-
438-
#### NgtsStageShadowsOptions
439-
440-
| Property | Description | Default Value |
441-
| ------------ | ------------------------------------------------------------ | ------------- |
442-
| `type` | The type of shadows. Can be `'contact'` or `'accumulative'`. | 'contact' |
443-
| `offset` | The shadow plane offset. | 0 |
444-
| `bias` | The shadow bias. | -0.0001 |
445-
| `normalBias` | The shadow normal bias. | 0 |
446-
| `size` | The shadow map size. | 1024 |
406+
## NgtsSpotLightShadow
447407

448-
By default it gives you contact shadows and auto-centering.
408+
A shadow caster that can help cast shadows of different patterns (textures) onto the scene.
449409

450-
```html
451-
<ngts-stage [options]="{ shadows: 'contact', adjustCamera: true, environment: 'city', intensity: 0.5 }">
452-
<ngt-mesh />
453-
</ngts-stage>
454-
```
410+
### Object Inputs (NgtsSpotLightShadowOptions)
455411

456-
For a little more realistic results enable accumulative shadows, which requires that the canvas, and models, can handle shadows.
412+
| Property | Description | Default Value |
413+
| ----------- | ----------------------------------------------------------- | ------------- |
414+
| `distance` | Distance between the shadow caster and light. | 0.4 |
415+
| `alphaTest` | Sets the alpha value to be used when running an alpha test. | 0.5 |
416+
| `scale` | Scale of the shadow caster plane. | 1 |
417+
| `width` | Width of the shadow map. The higher the more expensive. | 512 |
418+
| `height` | Height of the shadow map. The higher the more expensive. | 512 |
419+
| `map` | Texture - Pattern of the shadow. | |
457420

458421
```html
459-
<ngts-stage [options]="{shadows: 'accumulative'}">
460-
<ngt-mesh />
461-
</ngts-stage>
422+
<ngts-spot-light>
423+
<ngts-spot-light-shadow
424+
[options]="{
425+
distance: 0.4,
426+
alphaTest: 0.5,
427+
scale: 1,
428+
width: 512,
429+
height: 512,
430+
}"
431+
/>
432+
</ngts-spot-light>
462433
```
463434

464-
## NgtsCaustics
465-
466-
Caustics are swirls of light that appear when light passes through transmissive surfaces. This component uses a raymarching technique to project caustics onto a catcher plane. It is based on [github/N8python/caustics](https://github.com/N8python/caustics).
467-
468-
### Object Inputs (NgtsCausticsOptions)
469-
470-
| Property | Description | Default Value |
471-
| -------------- | --------------------------------------------------------------- | ------------- |
472-
| `frames` | How many frames it will render, set it to Infinity for runtime. | 1 |
473-
| `debug` | Enables visual cues to help you stage your scene. | false |
474-
| `causticsOnly` | Will display caustics only and skip the models. | false |
475-
| `backside` | Will include back faces and enable the backsideIOR prop. | false |
476-
| `ior` | The IOR refraction index. | 1.1 |
477-
| `backsideIOR` | The IOR refraction index for back faces. | 1.1 |
478-
| `worldRadius` | The texel size. | 0.3125 |
479-
| `intensity` | Intensity of the prjected caustics. | 0.05 |
480-
| `color` | Caustics color. | 'white' |
481-
| `resolution` | Buffer resolution. | 2048 |
482-
| `lightSource` | Camera position. | [5, 5, 5] |
483-
484-
It will create a transparent plane that blends the caustics of the objects it receives into your scene. It will only render once and not take resources any longer!
435+
An optional `shader` input lets you run a custom shader to modify/add effects to your shadow texture. The shader provides the following uniforms and varyings.
485436

486-
Make sure to use the `debug` flag to help you stage your contents. Like `NgtsContactShadows` and `NgtsAccumulativeShadows` the plane faces Y up.
437+
| Type | Name | Notes |
438+
| ------------------- | ------------ | -------------------------------------- |
439+
| `varying vec2` | `vUv` | UVs of the shadow casting plane |
440+
| `uniform sampler2D` | `uShadowMap` | The texture provided to the `map` prop |
441+
| `uniform float` | `uTime` | Current time |
487442

488-
```html
489-
<ngts-caustics [options]="{ debug: true }">
490-
<ngt-mesh />
491-
</ngts-caustics>
492-
```
493-
494-
Sometimes you want to combine caustics for even better visuals, or if you want to emulate multiple lightsources. Use the `causticsOnly` flag in such cases, and it will use the model inside only for calculations.
443+
Treat the output of the shader like an alpha map where `1` is opaque and `0` is transparent.
495444

496-
```html
497-
<ngts-caustics [options]="{ causticsOnly: true }">
498-
<ngt-mesh />
499-
</ngts-caustics>
445+
```glsl
446+
gl_FragColor = vec4(vec3(1.), 1.); // Opaque
447+
gl_FragColor = vec4(vec3(0.), 1.); // Transparent
500448
```
501449

502-
The light source can either be defined by prop or by reference. Use the latter if you want to control the light source, for instance in order to move or animate it. Runtime caustics with frames set to `Infinity`, a low resolution, and no backside can be feasible.
503-
504450
```html
505-
<ngt-object-3D #lightSource [position]="[ 2.5, 5, -2.5 ]" />
506-
507-
<ngts-caustics [options]="{ frames: Infinity, resolution: 256, lightSource }">
508-
<ngt-mesh />
509-
</ngts-caustics>
451+
<ngts-spot-light>
452+
<ngts-spot-light-shadow [shader]="customShader" [options]="shadowOptions" />
453+
</ngts-spot-light>
510454
```

0 commit comments

Comments
 (0)