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';

// Cesium dropped WebGL1: post-process shaders must be GLSL3
// (`in`/`out_FragColor`/`texture`), or shader compilation stops the render loop.
const bloomShader = `
  uniform sampler2D colorTexture;
  in vec2 v_textureCoordinates;
  void main() {
    vec4 color = texture(colorTexture, v_textureCoordinates);
    float brightness = (color.r + color.g + color.b) / 3.0;
    out_FragColor = vec4(color.rgb * (1.0 + brightness * 0.5), 1.0);
  }
`;

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

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

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

// `postProcessStages.remove()` destroys the removed stage, so re-activation
// needs a fresh instance: the getter re-evaluates on `isActive` changes.
const _stageControlled = usePostProcessStage(() => {
  if (!isActive.value)
    return undefined;
  return new Cesium.PostProcessStage({ name: 'bloomControlled', fragmentShader: bloomShader });
});
</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.
     *
     * Note: the default collection (`viewer.scene.postProcessStages`) destroys
     * a stage inside its `remove()` regardless of this option — a removed
     * stage can never be re-added. `false` only matters for custom
     * collections whose `remove` keeps removed stages alive.
     * @default true
     */
    destroyOnRemove?: boolean;
    /**
     * default value of `isActive`
     *
     * Removing a stage destroys it (see `destroyOnRemove`), so when toggled
     * back to `true` a previously removed stage is skipped with a console
     * warning instead of breaking the render loop. To toggle a stage on and
     * off, provide a getter that creates a fresh stage for each activation.
     * @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>;