# Loopfield Studio v1.1.0 사용 안내

[English](USER_GUIDE.md) · **한국어**

## 첫 영상

왼쪽 프리즘 블룸을 선택한다. 오른쪽에서 대칭 수와 빛의 겹을 바꾸고 팔레트를 선택한다. 화면 드래그는 선택한 레이어를 이동하고 휠은 확대한다. 이동이 과하면 **시점 초기화**를 누른다.

먼저 1080p · 30fps · 8초 · 고품질로 시도한다. **영상 내보내기**는 출력 설정을 여는 버튼이고, 오른쪽의 **MP4 렌더링**이 실제 렌더를 시작한다. 내 기기가 선택 설정을 지원하는지 확인한 다음 출력한다. 미리보기 품질은 작업 중 반응성만 바꾸며 MP4 해상도를 낮추지 않는다.

완료 후 다운로드 버튼이 나타난다. 디스크 직접 저장을 켠 경우에는 시작할 때 위치를 선택하고, 종료 시 해당 파일에 기록을 완료한다. 임시 출력이 완료된 것처럼 표시되지 않는다. 다운로드한 한 주기의 MP4는 플레이어의 반복 설정으로 계속 재생한다.

## 저장 해상도와 미리보기 품질

캔버스 아래의 **저장 해상도** 버튼은 실제 PNG/MP4 크기이다. 1080p는 1920×1080, 2K DCI는 2048×1080, 2K QHD는 2560×1440, 4K UHD는 3840×2160이다. QHD와 DCI 2K는 서로 다른 규격이다.

미리보기 품질의 540p/720p/1080p/1440p/2160p는 편집할 때의 GPU 부하만 바꾼다. 540p로 편집해도 저장 해상도를 4K로 선택하면 3840×2160으로 다시 렌더링한다. 4K 미리보기를 선택해야 4K로 저장되는 것은 아니다.

카메라 아이콘을 누르면 PNG 해상도 창이 열린다. 크기와 화면 비율을 확인하고 **PNG 저장**을 누른다. 이 대화상자의 설정은 MP4 출력에도 동일하게 반영된다.

## 코딩하지 않고 조합하기

**레이어 추가**를 누른 뒤 패턴을 고르면 현재 패턴을 교체하지 않고 새 레이어를 만든다. 일반 상태에서 프리셋을 고르면 선택한 레이어를 교체한다. 최대 4개이다. 복제·삭제·순서 변경·눈 아이콘으로 비교할 수 있다. 목록 앞쪽 레이어부터 배경 위에 쌓인다.

작업 중 숨긴 레이어는 계속 숨겨져 있지만, 페이지를 새로고침하면 자동 저장된 모든 레이어가 다시 보인다.

새 레이어는 스크린 합성이 기본이다. 검은 배경을 유지하면서 빛을 더하기 쉽다. 일반 합성은 위 레이어가 아래를 덮고, 곱하기는 어두워지기 쉽다. 차이 합성은 두 색의 차이를 보여 준다. 새 레이어의 불투명도를 0.15~0.4부터 조정하면 형태가 과하게 겹치는 것을 줄일 수 있다.

팔레트와 형태는 레이어별 설정이고 블룸·노출·대비·비네트·색수차는 합성된 전체 영상에 적용한다. 블룸은 화면을 밝히는 효과이지 HDR 영상 출력이 아니다. 시드는 코드가 uSeed를 사용하는 프리셋에서만 시각적 효과가 있다.

**형태** 옆의 **변경값 초기화**를 누르면 현재 선택한 레이어의 형태 슬라이더가 GLSL 기본값으로 돌아간다. 색상, 레이어의 확대·회전·위치, 전체 마무리 효과는 그대로 유지된다.

## 망델브로와 줄리아

망델브로는 픽셀마다 다른 c를 넣고 z=0에서 z²+c를 반복한다. 줄리아는 픽셀을 초기 z로 사용하고 하나의 c를 공유한다. 내부 점은 어둡게, 탈출하는 점은 반복 횟수 등을 이용해 칠한다.

반복 횟수를 올릴수록 경계의 계산이 늘어 GPU 부담이 커진다. 미리보기 540p로 조정한 뒤 실제 출력에서 세부를 확인한다. 확대는 최대 64이며 float 정밀도 때문에 극단적인 딥줌 탐색용이 아니다. 색을 부드럽게 바꾸더라도 H.264 압축과 SDR 8bit 특성상 아주 미세한 경계·그라데이션에는 차이가 생길 수 있다.

## 짧은 코딩

상단 **코드**를 누르면 데스크톱은 왼쪽 영상 / 오른쪽 편집기로 나뉜다. 가운데 구분선을 드래그하거나 포커스 후 좌우 방향키로 너비를 조절한다. Home은 기본 56%로 되돌린다. 상단 **패턴**과 **설정** 버튼으로 라이브러리·슬라이더를 연다. 760px 이하 스마트폰만 상하 배치이다. 선택 레이어의 코드가 편집기에 보인다. `vec3 pattern(vec2 p)`는 한 픽셀의 RGB 색을 반환한다. 0은 어둡고 1은 밝다. 시스템이 화면 그리기와 반복 호출을 처리하므로 WebGL 초기화 코드를 쓸 필요가 없다.

```glsl
// @slider uRings 2 24 1 10 | 고리 수
vec3 pattern(vec2 p) {
  float r = length(p);
  float rings = 0.5 + 0.5 * cos(r * uRings + uCycle.x);
  return palette(r + 0.15 * uCycle.y) * rings;
}
```

`@slider` 주석을 넣고 적용하면 오른쪽에 제어 항목이 생긴다. 편집한 코드는 **적용** 또는 Ctrl+Enter 후 화면에 반영된다. 에러가 나면 마지막 정상 영상이 유지되며 에러 메시지의 행 번호를 참고한다. 수정 중인 코드와 정상 적용 코드는 JSON에 별도로 보관한다. 적용되지 않은 코드가 있으면 MP4 출력 전에 적용하거나 되돌려야 한다.

## 루프 검사 읽기

검사기는 저해상도에서 위상 0, 1, 첫 이동 뒤, 마지막 이동 전의 네 장을 렌더한다. 시작과 끝의 평균 RGB 차이가 0.5/255 이하이면 샘플 일치로 표시한다. 최대 차이와 경계 움직임 차이도 함께 보여 준다.

이는 모든 픽셀과 시간에 대한 수학적 연속성 증명이 아니다. 출력 해상도에서 아주 작은 디테일이 튀거나 한 프레임 사이의 움직임이 너무 클 수 있으므로 완성 영상도 반복 재생해 확인한다. uTime을 직접 더한 직선 이동보다 sin(uAngle), cos(uAngle), uCycle을 쓰면 연결을 만들기 쉽다. 레이어 반복 횟수는 정수 1~8이다.

## 프로젝트 보관

현재 브라우저 저장소에 변경 내용을 자동 저장한다. 시크릿 모드, 저장 공간 부족, 브라우저 데이터 삭제, 도메인 변경에는 유지되지 않을 수 있다. 중요한 작업은 **프로젝트 저장**으로 JSON을 별도 보관한다. 자동 저장은 계정 동기화가 아니다.

**열기**에서 `.loopfield.json`을 선택한다. 파일에는 레이어·효과·출력 설정·GLSL과 미적용 초안이 들어 있다. PNG는 현재 선택한 출력 해상도로 현재 위상을 다시 렌더한다. 카메라 아이콘이 PNG 해상도 선택 창이다.

## 출력 실패 대응

HTTPS/localhost 오류라면 파일을 더블클릭하지 말고 정적 호스팅 주소로 연다. 원하는 해상도와 FPS에서 **실제 1프레임 출력 검사**를 누른다. 단순 지원 조회가 아니라 그 크기의 실제 WebGL 프레임을 H.264로 압축한다. 오래 걸리면 **검사 취소**로 중단한다. 첫 프레임 성공은 전체 길이의 성공을 보장하지 않는다.

자동 모드는 프로필·레벨·브라우저 인코더 선호와 프레임 전달 경로를 시도한다. 실패하면 **소프트웨어 우선**을 직접 선택해 해당 브라우저의 구현을 먼저 시도할 수 있다. 이 옵션은 브라우저에 주는 요청이지 앱이 소프트웨어 코덱을 추가 설치하는 기능이 아니다. 계속 실패하면 **진단 JSON 저장**으로 지원 조회/첫 프레임 실패 단계를 확인한다. 결과 창에서도 진단을 저장할 수 있다.

4K를 선택한 채 FPS나 압축 품질만 낮춰 다시 검사하면 해상도를 유지할 수 있다. 해당 크기의 브라우저 인코더가 전혀 없을 때는 브라우저/기기를 바꾸거나 사용자가 직접 해상도를 변경해야 한다. 앱은 자동으로 1080p 파일을 만들지 않는다. PNG는 H.264 인코더 없이도 해당 크기의 WebGL/PNG 렌더가 가능하면 저장된다.

메모리 경고가 나오면 직접 저장을 켜거나 길이·품질을 낮춘다. 직접 저장이 비활성이라면 그 브라우저에 해당 파일 API가 없는 것이다. 취소 시 완성 파일을 내보내지 않는다. 새 파일을 선택했다가 취소한 경우 OS/브라우저가 빈 이름의 파일을 남길 수 있다. 이미 존재하던 파일의 변경은 writer 완료 시점에 커밋하도록 요청한다.

기기가 절전으로 들어가거나 GPU가 재시작되면 출력이 끊길 수 있다. 작업 중 탭을 닫지 말고, 컨텍스트 오류가 나면 JSON을 보관한 뒤 새로고침한다. 큰 렌더를 GPU 드라이버가 처리 중이면 취소 응답이 지연될 수 있다.

## 키보드

Space는 재생/정지, Ctrl 또는 Cmd+S는 프로젝트 저장, Ctrl 또는 Cmd+Enter는 코드 적용이다. 코드 영역의 Tab은 두 칸을 넣으며 Esc를 누르면 적용 버튼으로 포커스가 이동한다. 대화상자에서는 Esc가 닫기 또는 출력 취소로 동작한다. 모션 줄이기 설정을 켠 사용자는 처음에 미리보기가 정지 상태로 열린다.

## 언어 전환

상단 EN / KR 버튼으로 즉시 전환합니다. 직접 입력한 프로젝트 이름, GLSL 원문과 미적용 초안, 재생 위치, 출력 설정은 그대로 유지됩니다. 언어 설정은 현재 브라우저에 저장됩니다. 동작 줄이기 설정에서는 내보내기 로고 애니메이션도 정지합니다.

## 기본 패턴과 제목

저장된 설정이 없는 첫 접속은 EN과 Prism Bloom으로 시작합니다. 제목은 선택한 패턴과 화면 언어에 맞게 자동으로 바뀝니다. 제목을 직접 입력하면 이후 패턴·언어 변경이나 새로고침에도 그대로 유지하며, JSON 저장·불러오기에도 이 설정을 보존합니다. 클릭만 하고 수정하지 않으면 자동 제목을 유지합니다. 새 프로젝트는 자동 제목으로 다시 시작합니다. 기존 프로젝트에 제목 모드 정보가 없으면 저장된 이름을 보존합니다.