usePostProcessStage

Reactively adds post-process effect PostProcessStage instances to a PostProcessStageCollection (defaults to viewer.scene.postProcessStages). Post-process effects apply to the rendered result of the whole scene (bloom, silhouette, black-and-white filters, etc.); usePostProcessStage automatically removes the previous batch when the data changes or the component unmounts and destroys instances by default (destroyOnRemove defaults to true). Note that toggling isActive to false triggers removal, and PostProcessStageCollection.remove always destroys the stage (destroyOnRemove: false cannot prevent it); re-adding a destroyed stage produces no effect — create a new instance each time you need to toggle.

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { usePostProcessStage } from 'vesium';
import { ref } from 'vue';

// create two bloom post process stages, one for each hook instance
const bloomShader = `
  uniform sampler2D colorTexture;
  varying vec2 v_textureCoordinates;
  void main() {
    vec4 color = texture2D(colorTexture, v_textureCoordinates);
    float brightness = (color.r + color.g + color.b) / 3.0;
    gl_FragColor = vec4(color.rgb * (1.0 + brightness * 0.5), 1.0);
  }
`;

const bloomStage = new Cesium.PostProcessStage({
  name: 'bloom',
  fragmentShader: bloomShader,
});

const bloomStageControlled = new Cesium.PostProcessStage({
  name: 'bloomControlled',
  fragmentShader: bloomShader,
});

// use the stage
const _stage = usePostProcessStage(bloomStage);

// control active state
const isActive = ref(true);

const _stageControlled = usePostProcessStage(bloomStageControlled, {
  isActive,
});
</script>

<template>
  <div class="p-10px">
    <button @click="isActive = !isActive">
      PostProcessStage: {{ isActive ? 'ON' : 'OFF' }}
    </button>
  </div>
</template>

import { PostProcessStage } from 'cesium';
import { usePostProcessStage } from 'vesium';

// The effect is defined by fragmentShader
const bloomStage = new PostProcessStage({
  name: 'bloom',
  fragmentShader: 'uniform sampler2D colorTexture; varying vec2 v_textureCoordinates; void main() { gl_FragColor = texture2D(colorTexture, v_textureCoordinates); }',
});

const controlled = usePostProcessStage(bloomStage, {
  isActive: true, // false removes the stage; Cesium's remove always destroys it
});

Options

• collection - The target PostProcessStageCollection; defaults to useViewer().value.scene.postProcessStages.
• destroyOnRemove - Whether the hook additionally calls destroy() on removal, defaults to true. Note that Cesium's PostProcessStageCollection.remove always destroys the stage; this option cannot prevent it.
• isActive - Whether active, defaults to true; when false, the stage is not added and the effect does not apply.
• evaluating - A ref receiving the async evaluation state.

Return Value

• A single value (or getter/ref/async getter) returns ComputedRef<T | undefined>.
• An array returns ComputedRef<T[] | undefined>.

Notes

• When the same stage instance is managed by multiple usePostProcessStage hooks at once, removal and destruction by one of them affects the other holders; manage each instance with a single hook.
• Cleanup calls collection.remove(item) unconditionally (unlike useDataSource/usePrimitive, it does not check whether the collection has been destroyed); do not rely on this hook's cleanup after the viewer is destroyed.

Type Definitions

import type { PostProcessStage, PostProcessStageCollection } from 'cesium';
import type { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
import type { MaybeRefOrAsyncGetter } from '../toPromiseValue';
export interface UsePostProcessStageOptions {
    /**
     * The collection of PostProcessStage to be added
     * @default useViewer().scene.postProcessStages
     */
    collection?: PostProcessStageCollection;
    /**
     * Whether to destroy the stage when removed from the collection.
     * When true, the stage's GPU resources will be released.
     * @default true
     */
    destroyOnRemove?: boolean;
    /**
     * default value of `isActive`
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
    /**
     * Ref passed to receive the updated of async evaluation
     */
    evaluating?: Ref<boolean>;
}
/**
 * Add `PostProcessStage` to the `PostProcessStageCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `PostProcessStage`.
 *
 * Overload 1: Parameter supports passing in a single value.
 */
export declare function usePostProcessStage<T extends PostProcessStage = PostProcessStage>(stage?: MaybeRefOrAsyncGetter<T | undefined>, options?: UsePostProcessStageOptions): ComputedRef<T | undefined>;
/**
 * Add `PostProcessStage` to the `PostProcessStageCollection`, automatically update when the data changes, and destroy the side effects caused by the previous `PostProcessStage`.
 *
 * Overload 2: Parameter supports passing in an array.
 */
export declare function usePostProcessStage<T extends PostProcessStage = PostProcessStage>(stages?: MaybeRefOrAsyncGetter<Array<T | undefined> | undefined>, options?: UsePostProcessStageOptions): ComputedRef<T[] | undefined>;