angular-three-postprocessing 4.0.0-next.99 → 4.0.0

package/n8ao/README.md

@@ -1,3 +1,146 @@
 # angular-three-postprocessing/n8ao
 
 Secondary entry point of `angular-three-postprocessing`. It can be used by importing from `angular-three-postprocessing/n8ao`.
+
+## Installation
+
+This package requires `angular-three-postprocessing` and `n8ao` as peer dependencies.
+
+```bash
+npm install angular-three-postprocessing n8ao postprocessing
+```
+
+## NgtpN8AO
+
+A high-quality screen-space ambient occlusion (SSAO) effect component. N8AO adds realistic shadowing to crevices, corners, and areas where objects meet, greatly enhancing the visual depth of 3D scenes.
+
+### Basic Usage
+
+```html
+<ngtp-effect-composer>
+	<ngtp-n8ao />
+</ngtp-effect-composer>
+```
+
+### With Custom Options
+
+```html
+<ngtp-effect-composer>
+	<ngtp-n8ao
+		[options]="{
+    intensity: 3,
+    aoRadius: 2,
+    aoSamples: 32
+  }"
+	/>
+</ngtp-effect-composer>
+```
+
+### Using Quality Presets
+
+```html
+<ngtp-effect-composer>
+	<ngtp-n8ao [options]="{ quality: 'high' }" />
+</ngtp-effect-composer>
+```
+
+### Component Example
+
+```typescript
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { NgtCanvas, extend } from 'angular-three';
+import { NgtpEffectComposer } from 'angular-three-postprocessing';
+import { NgtpN8AO } from 'angular-three-postprocessing/n8ao';
+import * as THREE from 'three';
+
+extend(THREE);
+
+@Component({
+	selector: 'app-scene',
+	standalone: true,
+	imports: [NgtpEffectComposer, NgtpN8AO],
+	schemas: [CUSTOM_ELEMENTS_SCHEMA],
+	template: `
+		<ngt-mesh>
+			<ngt-box-geometry />
+			<ngt-mesh-standard-material />
+		</ngt-mesh>
+
+		<ngtp-effect-composer>
+			<ngtp-n8ao [options]="aoOptions" />
+		</ngtp-effect-composer>
+	`,
+})
+export class SceneComponent {
+	aoOptions = {
+		intensity: 4,
+		aoRadius: 3,
+		quality: 'medium' as const,
+	};
+}
+```
+
+## Options
+
+### Quality Presets
+
+| Preset          | Description                      |
+| --------------- | -------------------------------- |
+| `'performance'` | Fastest, lowest quality          |
+| `'low'`         | Low quality, good performance    |
+| `'medium'`      | Balanced quality and performance |
+| `'high'`        | High quality, slower             |
+| `'ultra'`       | Highest quality, most demanding  |
+
+### All Options
+
+| Option                   | Type                                                      | Default   | Description                                                                   |
+| ------------------------ | --------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
+| `quality`                | `'performance' \| 'low' \| 'medium' \| 'high' \| 'ultra'` | -         | Quality preset (overrides individual settings)                                |
+| `intensity`              | `number`                                                  | `5`       | Strength of the AO effect                                                     |
+| `aoRadius`               | `number`                                                  | `5.0`     | Radius of the AO effect in world units                                        |
+| `aoSamples`              | `number`                                                  | `16`      | Number of samples for AO calculation (higher = better quality)                |
+| `aoTones`                | `number`                                                  | `0.0`     | Number of tones for AO gradient                                               |
+| `distanceFalloff`        | `number`                                                  | `1.0`     | How quickly the AO effect falls off with distance                             |
+| `color`                  | `ColorRepresentation`                                     | `'black'` | Color of the AO shadows                                                       |
+| `denoiseSamples`         | `number`                                                  | `8`       | Number of samples for denoising                                               |
+| `denoiseRadius`          | `number`                                                  | `12`      | Radius of the denoising filter                                                |
+| `denoiseIterations`      | `number`                                                  | `2.0`     | Number of denoising iterations                                                |
+| `halfRes`                | `boolean`                                                 | `false`   | Render at half resolution for better performance                              |
+| `depthAwareUpsampling`   | `boolean`                                                 | `true`    | Use depth-aware upsampling when using half resolution                         |
+| `screenSpaceRadius`      | `boolean`                                                 | `false`   | Use screen-space radius instead of world-space                                |
+| `renderMode`             | `0 \| 1 \| 2 \| 3 \| 4`                                   | `0`       | Debug render mode (0: Combined, 1: AO only, 2: Normals, 3: Depth, 4: Denoise) |
+| `biasOffset`             | `number`                                                  | `0.0`     | Bias offset for depth comparison                                              |
+| `biasMultiplier`         | `number`                                                  | `0.0`     | Bias multiplier for depth comparison                                          |
+| `gammaCorrection`        | `boolean`                                                 | `true`    | Apply gamma correction                                                        |
+| `logarithmicDepthBuffer` | `boolean`                                                 | `false`   | Use logarithmic depth buffer                                                  |
+| `colorMultiply`          | `boolean`                                                 | `true`    | Multiply the color instead of darkening                                       |
+| `transparencyAware`      | `boolean`                                                 | `false`   | Handle transparent objects correctly                                          |
+| `accumulate`             | `boolean`                                                 | `false`   | Accumulate samples over frames for better quality                             |
+
+## Tips
+
+### Performance vs Quality
+
+- Use `quality: 'performance'` or `halfRes: true` for better frame rates
+- Increase `aoSamples` for higher quality at the cost of performance
+- Use `accumulate: true` for static scenes to get better quality over time
+
+### Common Configurations
+
+```html
+<!-- Performance-focused -->
+<ngtp-n8ao [options]="{ quality: 'performance', halfRes: true }" />
+
+<!-- Quality-focused -->
+<ngtp-n8ao [options]="{ quality: 'ultra', aoSamples: 64, denoiseSamples: 16 }" />
+
+<!-- Subtle effect -->
+<ngtp-n8ao [options]="{ intensity: 2, aoRadius: 1 }" />
+
+<!-- Strong, dramatic effect -->
+<ngtp-n8ao [options]="{ intensity: 10, aoRadius: 8, color: '#000000' }" />
+
+<!-- Debug AO only -->
+<ngtp-n8ao [options]="{ renderMode: 1 }" />
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "angular-three-postprocessing",
-	"version": "4.0.0-next.99",
+	"version": "4.0.0",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -22,12 +22,12 @@
 	],
 	"license": "MIT",
 	"peerDependencies": {
-		"@angular/common": ">=19.0.0 <20.0.0",
-		"@angular/core": ">=19.0.0 <20.0.0",
+		"@angular/common": ">=20.0.0 <22.0.0",
+		"@angular/core": ">=20.0.0 <22.0.0",
 		"maath": ">=0.10.0 <0.11.0",
 		"n8ao": ">=1.9.4 <2.0.0",
 		"postprocessing": "^6.0.0",
-		"three": ">=0.156.0 <0.175.0",
+		"three": ">=0.157.0 <0.183.0",
 		"three-stdlib": "^2.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -44,17 +44,17 @@
 		"node_modules/angular-three/web-types.json"
 	],
 	"module": "fesm2022/angular-three-postprocessing.mjs",
-	"typings": "index.d.ts",
+	"typings": "types/angular-three-postprocessing.d.ts",
 	"exports": {
 		"./package.json": {
 			"default": "./package.json"
 		},
 		".": {
-			"types": "./index.d.ts",
+			"types": "./types/angular-three-postprocessing.d.ts",
 			"default": "./fesm2022/angular-three-postprocessing.mjs"
 		},
 		"./n8ao": {
-			"types": "./n8ao/index.d.ts",
+			"types": "./types/angular-three-postprocessing-n8ao.d.ts",
 			"default": "./fesm2022/angular-three-postprocessing-n8ao.mjs"
 		}
 	}

package/types/angular-three-postprocessing-n8ao.d.ts

@@ -0,0 +1,167 @@
+import * as _angular_core from '@angular/core';
+import * as THREE from 'three';
+
+/**
+ * Configuration options for the N8AO (N8 Ambient Occlusion) effect.
+ *
+ * N8AO is a high-quality, screen-space ambient occlusion implementation
+ * that provides realistic shadowing in crevices and corners.
+ */
+interface NgtpN8AOOptions {
+    /**
+     * Radius of the ambient occlusion effect in world units.
+     * @default 5.0
+     */
+    aoRadius: number;
+    /**
+     * Number of tones for AO gradient.
+     * @default 0.0
+     */
+    aoTones: number;
+    /**
+     * How quickly the AO effect falls off with distance.
+     * @default 1.0
+     */
+    distanceFalloff: number;
+    /**
+     * Intensity/strength of the ambient occlusion effect.
+     * @default 5
+     */
+    intensity: number;
+    /**
+     * Bias offset for depth comparison.
+     * @default 0.0
+     */
+    biasOffset: number;
+    /**
+     * Bias multiplier for depth comparison.
+     * @default 0.0
+     */
+    biasMultiplier: number;
+    /**
+     * Number of samples for ambient occlusion calculation.
+     * Higher values = better quality but slower.
+     * @default 16
+     */
+    aoSamples: number;
+    /**
+     * Number of samples for denoising.
+     * @default 8
+     */
+    denoiseSamples: number;
+    /**
+     * Radius of the denoising filter.
+     * @default 12
+     */
+    denoiseRadius: number;
+    /**
+     * Color of the ambient occlusion shadows.
+     * @default 'black'
+     */
+    color: THREE.ColorRepresentation;
+    /**
+     * Whether to render at half resolution for better performance.
+     * @default false
+     */
+    halfRes: boolean;
+    /**
+     * Whether to use depth-aware upsampling when using half resolution.
+     * @default true
+     */
+    depthAwareUpsampling: boolean;
+    /**
+     * Whether to use screen-space radius instead of world-space.
+     * @default false
+     */
+    screenSpaceRadius: boolean;
+    /**
+     * Render mode for debugging and visualization.
+     * 0: Combined, 1: AO only, 2: Normals, 3: Depth, 4: Denoise
+     * @default 0
+     */
+    renderMode: 0 | 1 | 2 | 3 | 4;
+    /**
+     * Number of iterations for the denoising filter.
+     * @default 2.0
+     */
+    denoiseIterations: number;
+    /**
+     * Whether to handle transparent objects correctly.
+     * @default false
+     */
+    transparencyAware: boolean;
+    /**
+     * Whether to apply gamma correction.
+     * @default true
+     */
+    gammaCorrection: boolean;
+    /**
+     * Whether to use logarithmic depth buffer.
+     * @default false
+     */
+    logarithmicDepthBuffer: boolean;
+    /**
+     * Whether to multiply the color instead of darkening.
+     * @default true
+     */
+    colorMultiply: boolean;
+    /**
+     * Whether to accumulate samples over frames for better quality.
+     * @default false
+     */
+    accumulate: boolean;
+    /**
+     * Quality preset that overrides individual settings.
+     * Options: 'performance', 'low', 'medium', 'high', 'ultra'
+     * @default undefined
+     */
+    quality?: 'performance' | 'low' | 'medium' | 'high' | 'ultra';
+}
+/**
+ * Angular component that applies N8AO (N8 Ambient Occlusion) to the scene.
+ *
+ * N8AO is a high-quality screen-space ambient occlusion effect that adds
+ * realistic shadowing to crevices, corners, and areas where objects meet.
+ * It provides various quality presets and fine-grained control over the
+ * AO appearance.
+ *
+ * @example
+ * ```html
+ * <ngtp-effect-composer>
+ *   <ngtp-n8ao [options]="{ intensity: 3, aoRadius: 2 }" />
+ * </ngtp-effect-composer>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Using quality preset -->
+ * <ngtp-effect-composer>
+ *   <ngtp-n8ao [options]="{ quality: 'high' }" />
+ * </ngtp-effect-composer>
+ * ```
+ */
+declare class NgtpN8AO {
+    /**
+     * Configuration options for the N8AO effect.
+     * @see NgtpN8AOOptions
+     */
+    options: _angular_core.InputSignalWithTransform<NgtpN8AOOptions, "" | Partial<NgtpN8AOOptions>>;
+    private quality;
+    private effectComposer;
+    /**
+     * The underlying N8AOPostPass instance.
+     * Created with the scene and camera from the effect composer.
+     */
+    protected effect: _angular_core.Signal<any>;
+    constructor();
+    /**
+     * Applies a quality preset to the effect.
+     * Converts the quality string to title case and calls the effect's setQuality method.
+     */
+    private setQualityEffect;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgtpN8AO, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgtpN8AO, "ngtp-n8ao", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgtpN8AO };
+export type { NgtpN8AOOptions };