# shaderTest

**Repository Path**: M_Fisher/shader-test

## Basic Information

- **Project Name**: shaderTest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Shader 测试台

Vue 3 + Vite + Three.js 的多 shader 测试框架：每个 shader 测试是一个独立页面，左侧边栏导航切换，
路由格式为 `/#/shader/<id>`，快捷键 `[` / `]` 可在相邻测试间跳转。

## 快速开始

```bash
npm install
npm run dev     # 开发，默认 http://localhost:5173
npm run build   # 生产构建
```

## 目录结构

```
src/
├── main.js                  # 入口
├── App.vue                  # 布局：侧边栏 + 顶栏 + <RouterView>
├── router.js                # 路由由注册表自动生成，不用手改
├── style.css                # 全局样式（含 .canvas-host 舞台铺满规则）
├── composables/
│   └── useThree.js          # Three.js 生命周期封装（渲染循环 / resize / 资源释放）
└── shaders/
    ├── index.js             # ★ 注册表：新增测试只需要改这个文件
    ├── gradient-flow/       # 示例 1：全屏片元着色器（2D 效果）
    ├── noise-blob/          # 示例 2：网格 + 顶点位移 + OrbitControls
    └── star-field/          # 示例 3：GPU 粒子（Points）
```

## 如何新增一个 shader 测试

**第 1 步**：在 `src/shaders/` 下新建文件夹，写一个组件和一个注册项。
GLSL 文件用 `?raw` 后缀导入即可作为字符串使用（Vite 内置支持，无需插件）。

组件模板（把场景搭建写在 `useThree` 的回调里即可）：

```vue
<script setup>
import { ref } from 'vue'
import * as THREE from 'three'
import { useThree } from '../../composables/useThree'
import vertexShader from './vertex.glsl?raw'
import fragmentShader from './fragment.glsl?raw'

const container = ref(null)

useThree(container, (ctx) => {
  // ctx = { THREE, renderer, scene, camera }
  const uniforms = { uTime: { value: 0 } }
  ctx.scene.add(new THREE.Mesh(geometry, new THREE.ShaderMaterial({ uniforms, vertexShader, fragmentShader })))

  return {
    update(dt, elapsed) { uniforms.uTime.value = elapsed }, // 每帧
    onResize(w, h) {},                                      // 容器尺寸变化
    dispose() {},                                           // 需要 OrbitControls 等额外清理时
  }
})
</script>

<template>
  <!-- 类名必须是 canvas-host，会自动铺满右侧舞台区域 -->
  <div ref="container" class="canvas-host"></div>
</template>
```

**第 2 步**：在 `src/shaders/index.js` 里注册：

```js
import MyTest from './my-test/MyTest.vue'

export const shaders = [
  // ...已有的测试,
  { id: 'my-test', title: '我的测试', description: '一句话描述', component: MyTest },
]
```

侧边栏、路由、顶栏的标题和上/下翻页都会自动生效。

## 约定

- **uniform 命名**：`uTime`（秒）、`uResolution`（像素 vec2）等以 `u` 为前缀；自定义 attribute 以 `a` 为前缀。
- **不要在 glsl 文件里声明 `precision highp float;`**——`THREE.ShaderMaterial` 会自动注入前缀，重复声明会编译报错；`position` / `uv` / `normal` 等 attribute 和矩阵 uniform 也是自动注入的，同样不要重复声明。
- 组件根节点直接写 `<div class="canvas-host" ref="container"></div>`，布局由全局样式负责。
- 相机默认是 `PerspectiveCamera(60°)` 位于 z=5，可在 setup 回调里调整或整个替换 `ctx.camera`，resize 时会按 `ctx.camera` 当前值自适应。