usePostProcessStage

将后处理特效 PostProcessStage 响应式地加入 PostProcessStageCollection（默认 viewer.scene.postProcessStages）。后处理作用于整个场景的渲染结果（泛光、描边、黑白滤镜等），usePostProcessStage 在数据变化或组件卸载时自动移除上一批 stage，移除时默认销毁实例（destroyOnRemove 默认 true）。注意 isActive 切到 false 会触发移除，而 PostProcessStageCollection.remove 会无条件销毁 stage（destroyOnRemove: false 无法阻止），销毁后的 stage 重新加入也不会产生特效——反复开关需要每次创建新实例。

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

// 特效由 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 时移除；Cesium 的 remove 会无条件销毁 stage
});

配置项

• collection - 目标 PostProcessStageCollection，默认 useViewer().value.scene.postProcessStages。
• destroyOnRemove - 移除时是否由 hook 额外调用 destroy()，默认 true。注意 Cesium 的 PostProcessStageCollection.remove 会无条件销毁 stage，此选项无法阻止。
• isActive - 是否激活，默认 true；为 false 时不加入集合，特效不生效。
• evaluating - 接收异步求值状态的 ref。

返回值

• 传入单个值（或 getter/ref/异步 getter）返回 ComputedRef<T | undefined>。
• 传入数组返回 ComputedRef<T[] | undefined>。

注意事项

• 同一个 stage 实例被多个 usePostProcessStage 同时管理时，其中一个移除并销毁实例会影响其他持有者；建议每个实例只由一个 hook 管理。
• 清理时无条件调用 collection.remove(item)（不做集合销毁检查，与 useDataSource/usePrimitive 不同），viewer 销毁后请勿依赖本 hook 的清理。

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