# LUT Cycler — 설명서

> 최초 작성: 2026-04-06
> 대상 버전: Unity URP (Universal Render Pipeline)

---

## 개요

Volume의 Color Lookup (LUT) 텍스처를 빠르게 탐색·비교·즐겨찾기 할 수 있는 에디터 도구 및 런타임 컴포넌트 세트.

- **에디터 모드**: LUT Browser 윈도우에서 썸네일 클릭으로 즉시 Volume에 적용
- **플레이 모드**: 스크롤 휠(또는 방향키)로 LUT 순환
- **즐겨찾기**: 마음에 드는 LUT를 ★ 표시로 저장, 필터링

---

## 폴더 구조

```
Assets/YAMO/LutCycler/
├── LUTs/                          ← LUT 텍스처 파일을 여기에 배치
├── Prefabs/
│   ├── LUT Controller.prefab      ← 씬에 드롭해서 사용하는 프리팹
│   └── LUT_Profile.asset          ← Volume이 참조하는 VolumeProfile
├── Scripts/
│   └── LutCycler.cs               ← 런타임 컴포넌트
└── Editor/
    └── LutBrowserWindow.cs        ← 에디터 전용 창
```

---

## 의존성 및 환경 요건

| 항목 | 내용 |
|------|------|
| 렌더 파이프라인 | **URP** (Universal Render Pipeline) |
| Input System | **New Input System** 패키지 필요 (`UnityEngine.InputSystem`) |
| Unity 최소 버전 | 2021.x 이상 권장 |
| 네임스페이스 | `YAMO.LutCycler` (런타임), `YAMO.LutCycler.Editor` (에디터) |

> **주의**: Input System 패키지가 설치되어 있지 않으면 런타임에서 `InvalidOperationException`이 발생한다.
> Package Manager → `Input System` 설치 후 Player Settings의 Active Input Handling을 `Input System Package (New)` 또는 `Both`로 설정할 것.

---

## 파일별 설계 및 역할

### `Scripts/LutCycler.cs`

런타임 MonoBehaviour. `Volume` 컴포넌트와 함께 동작한다.

**인스펙터 필드**

| 필드 | 설명 |
|------|------|
| `lutTextures` | 순환할 LUT 텍스처 목록 |
| `currentIndex` | 현재 적용 중인 인덱스 (읽기 참고용) |
| `favorites` | 즐겨찾기한 텍스처 목록 |
| `useScrollWheel` | 스크롤 휠로 순환 (기본 ON) |
| `useArrowKeys` | 좌우 방향키로 순환 (기본 OFF) |

**주요 공개 메서드**

| 메서드 | 설명 |
|--------|------|
| `CycleNext()` | 다음 LUT로 이동 |
| `CyclePrevious()` | 이전 LUT로 이동 |
| `ApplyAt(int index)` | 특정 인덱스의 LUT 적용 |
| `ApplyCurrent()` | 현재 인덱스 LUT를 Volume에 강제 반영 |
| `ToggleFavorite(Texture2D)` | 즐겨찾기 추가/제거 토글 |
| `IsFavorite(Texture2D)` | 즐겨찾기 여부 반환 |
| `GetCurrentTexture()` | 현재 LUT 텍스처 반환 |
| `GetCurrentIndex()` | 현재 인덱스 반환 |

**컨텍스트 메뉴 (인스펙터 우클릭)**

- `Load LUTs from Folder` — `Assets/YAMO/LutCycler/LUTs` 폴더에서 텍스처 자동 로드
- `Clear Favorites` — 즐겨찾기 전체 초기화

**내부 동작 흐름**

```
Awake → Volume에서 ColorLookup 참조 획득
Start → ApplyCurrent() 호출 (0번 LUT 적용)
Update → 입력 감지 → CycleNext / CyclePrevious
       → ApplyCurrent() → EnsureColorLookup() → ColorLookup.texture.value 갱신
```

**Input System 분기 처리**

`#if ENABLE_INPUT_SYSTEM` 컴파일 심볼로 New/Old Input System을 자동 분기.
New Input System 사용 시 `Mouse.current.scroll`, `Keyboard.current` API를 사용.

---

### `Editor/LutBrowserWindow.cs`

에디터 전용 `EditorWindow`. 메뉴 `YAMO` 아래에 등록된다.

**메뉴 항목**

| 메뉴 | 동작 |
|------|------|
| `YAMO/LUT Browser` | LUT Browser 윈도우 열기 |
| `YAMO/Create LUT Controller` | 씬에 LUT Controller GameObject 생성 및 프리팹 저장 |

**Create LUT Controller 동작 순서**

1. `Prefabs/LUT_Profile.asset`이 없으면 새로 생성 (ColorLookup Override 포함)
2. 씬에 `LUT Controller` GameObject 생성
3. `Volume` 컴포넌트 추가 (isGlobal = true, profile = LUT_Profile)
4. `LutCycler` 컴포넌트 추가 후 `LoadFromFolder()` 호출
5. `Prefabs/LUT Controller.prefab`으로 저장

**LUT Browser 윈도우 구성**

```
[ ↻ Refresh ] [ 크기 슬라이더 ] [ ★ 즐겨찾기만 ] [ 검색창 ]   ← 툴바
[ 현재 LUT 이름 | 전체 N개 | ★ M개 ]                         ← 상태바
┌──────┐ ┌──────┐ ┌──────┐                                   ← 썸네일 그리드
│ 썸네일 │ │ 썸네일 │ │ 썸네일 │   (창 너비에 따라 열 수 자동 계산)
│ 이름 ☆│ │ 이름 ★│ │ 이름 ☆│
└──────┘ └──────┘ └──────┘
```

**썸네일 카드 동작**

- 썸네일 클릭 → `ApplyLutToScene()` 호출
  - 플레이 모드: `LutCycler.ApplyAt()` 경유
  - 에디터 모드: `VolumeProfile`에 직접 `Undo` 기록 후 적용
- `☆/★` 버튼 클릭 → `LutCycler.ToggleFavorite()` 호출
- 현재 적용 중인 LUT는 파란 테두리로 강조
- 즐겨찾기 LUT는 썸네일 좌상단에 `★` 오버레이

**씬에 LutCycler가 없을 경우**
상태바에 경고 표시. 썸네일 클릭 시 씬의 첫 번째 `Volume`에 직접 적용. 즐겨찾기 기능은 동작하지 않음.

---

## 사용 방법

### 초기 세팅

1. `Assets/YAMO/LutCycler/LUTs/` 폴더에 LUT 텍스처 파일 복사
2. 유니티 메뉴 **YAMO → Create LUT Controller** 실행
   - 씬에 `LUT Controller` 오브젝트가 생성되고 프리팹으로 저장됨
   - LUTs 폴더의 텍스처가 자동으로 `lutTextures` 리스트에 등록됨
3. 메뉴 **YAMO → LUT Browser** 로 브라우저 창 열기

### LUT 탐색 (에디터 모드)

- 브라우저 창에서 썸네일 클릭 → 씬 뷰에 즉시 반영
- `↻ Refresh` → LUTs 폴더 재스캔
- 검색창에 이름 입력 → 필터링
- 크기 슬라이더로 썸네일 크기 조절

### LUT 순환 (플레이 모드)

- 스크롤 휠 위/아래로 다음/이전 LUT 전환
- 인스펙터에서 `Use Arrow Keys` 체크 시 좌우 방향키도 사용 가능
- 현재 인덱스는 인스펙터 `Current Index` 필드에서 확인

### 즐겨찾기

- 브라우저 창의 `☆` 버튼 클릭으로 즐겨찾기 등록/해제
- `★ 즐겨찾기만` 토글로 즐겨찾기 LUT만 표시
- 즐겨찾기 목록은 `LutCycler` 컴포넌트의 `Favorites` 리스트에 저장됨 (프리팹에 직렬화)
- 인스펙터 우클릭 → `Clear Favorites`로 전체 초기화

### LUT 텍스처 추가

1. `Assets/YAMO/LutCycler/LUTs/`에 파일 복사
2. 브라우저 창에서 `↻ Refresh` 클릭 (브라우저 목록 갱신)
3. LutCycler 인스펙터 우클릭 → `Load LUTs from Folder` (런타임 순환 목록 갱신)

---

## 유지보수 메모

- LUT 폴더 경로를 변경하려면 `LutCycler.cs`의 `LoadFromFolder()` 상수와 `LutBrowserWindow.cs`의 `LUT_FOLDER` 상수를 함께 수정할 것.
- 즐겨찾기 데이터는 `LutCycler` 컴포넌트에 직렬화된다. 프리팹을 삭제하면 즐겨찾기가 초기화되므로 주의.
- `VolumeProfile` (`LUT_Profile.asset`)은 `Create LUT Controller` 실행 시 자동 생성된다. 이미 존재하면 재사용한다.
- `EditorStyles.toolbarLabel`은 Unity에 존재하지 않는 스타일 — `EditorStyles.miniLabel`을 사용할 것.