-
Notifications
You must be signed in to change notification settings - Fork 0
07 FAQ
miniRT 사용 중 자주 발생하는 질문과 답변입니다.
A: MinilibX 서브모듈을 초기화하지 않았습니다.
git submodule update --init --recursive
make reA: X11 개발 라이브러리가 설치되지 않았습니다.
sudo apt-get install libx11-dev libxext-dev libbsd-dev
make reA: Xcode Command Line Tools를 설치하세요.
xcode-select --installA: 실행 권한과 장면 파일 경로를 확인하세요.
chmod +x miniRT
./miniRT scenes/test_simple.rtA: 장면 파일 경로가 올바른지 확인하세요.
ls -la scenes/test_simple.rt
./miniRT /full/path/to/scene.rt # 절대 경로 사용A: 장면 파일 형식이 올바른지 확인하세요.
cat scenes/test_simple.rt # 파일 내용 확인필수 요소(A, C, L)가 모두 있는지 확인하고, 카메라가 객체를 바라보는지 확인하세요.
A: BVH는 자동으로 활성화됩니다. 다음을 확인하세요:
- 객체 수: 50개 이상이면 초기 BVH 빌드에 시간이 걸립니다.
- 해상도: 800x600이 기본입니다.
- Soft Shadow: 인터랙션 중에는 자동으로 1 sample로 축소됩니다.
A: Shadow Acne 현상입니다. 이미 적응형 Shadow Bias가 적용되어 있지만, 매우 얇은 객체에서는 발생할 수 있습니다.
A: 자기 교차(Self-intersection) 문제입니다. Shadow Bias가 충분하지 않을 수 있습니다.
A: 올바른 키를 사용하고 있는지 확인하세요:
- 이동: W/A/S/D/Q/Z
- 회전: E/C
- 리셋: S
대소문자를 구분하지 않습니다.
A:
-
[또는]키를 눌러 객체를 순환 선택합니다. - HUD를 켜서 (H 키) 선택된 객체 정보를 확인하세요.
A: H 키를 눌러 HUD를 토글하세요. 기본적으로 표시됩니다.
A: miniRT는 메모리 누수 0을 목표로 합니다. 다음을 확인하세요:
# Linux
valgrind --leak-check=full ./miniRT scenes/test_simple.rt
# macOS
leaks -atExit -- ./miniRT scenes/test_simple.rtESC 키로 정상 종료하면 모든 메모리가 해제되어야 합니다.
A:
- 장면 파일 형식이 올바른지 확인
- 모든 벡터가 정규화되어 있는지 확인 (특히 법선 벡터)
- 지름/높이 등이 양수인지 확인
A: 씬 파일 형식을 참조하세요. 기본 예제:
A 0.2 255,255,255
C 0,0,20 0,0,-1 70
L -10,10,10 0.7 255,255,255
sp 0,0,0 10 255,0,0
pl 0,-5,0 0,1,0 200,200,200
A: 현재 버전은 단일 광원만 지원합니다.
A: 이론적으로 제한이 없지만, 객체가 많을수록 렌더링이 느려집니다. BVH를 사용하면 성능이 크게 향상됩니다.
A:
- 작은 FOV (30-60°): 망원 렌즈 효과, 좁은 시야
- 중간 FOV (60-90°): 자연스러운 시야
- 큰 FOV (90-120°): 광각 렌즈 효과, 왜곡 발생
C 0,0,20 0,0,-1 30 # 망원
C 0,0,20 0,0,-1 70 # 표준
C 0,0,20 0,0,-1 120 # 광각
A: 현재 버전은 직접 조명만 지원합니다. 반사는 추가 광선 추적이 필요하며, 향후 업데이트에서 지원될 예정입니다.
A: 픽셀당 여러 샘플을 사용하면 가능하지만, 현재 버전에서는 지원하지 않습니다.
A: 다음 순서로 학습하세요:
- 프로그램 개요
- 레이 트레이싱 알고리즘
- 조명 시스템
- 실제 코드 읽기 (
src/ray/,src/lighting/)
A: 소스 코드를 직접 읽어보세요. 주요 디렉토리:
-
src/ray/- 광선 추적 로직 -
src/lighting/- 조명 계산 -
src/spatial/- BVH 가속 구조 -
src/render/- 렌더링 파이프라인
A: 42 School의 코딩 스타일 가이드입니다. 주요 규칙:
- 함수당 최대 25줄
- 파일당 최대 5개 함수
- 함수 파라미터 최대 4개
- 금지된 키워드: for, switch, do-while 등
# Norminette 검사
norminette src/ includes/- 문서 확인: Wiki 홈에서 관련 문서 찾기
- 코드 확인: 소스 코드의 주석 읽기
- 이슈 생성: GitHub Issues에 상세한 설명과 함께 제보
- OS 및 버전 (예: Ubuntu 20.04, macOS 11.6)
- 빌드 방법 (make, make re)
- 장면 파일 내용
- 에러 메시지 (전체 출력)
- 예상 동작 vs 실제 동작
A: BVH(Bounding Volume Hierarchy)는 v2.1.0에 추가된 공간 가속 구조입니다.
개요:
- 장면의 객체들을 이진 트리로 구성
- 광선-객체 교차 검사를 O(n)에서 O(log n)으로 최적화
- 복잡한 장면(50개 이상 객체)에서 2-10배 속도 향상
특징:
- v2.1.0부터 기본 활성화
- AABB(축 정렬 경계 상자) 기반 트리 구조
- 별도 설정 불필요
상세한 내용은 레이 트레이싱 알고리즘을 참조하세요.
A: 성능 저하의 원인은 여러 가지일 수 있습니다.
해결 방법:
-
BVH 활성화 확인
- v2.1.0 이상 버전을 사용하고 있는지 확인
- BVH는 기본 활성화되어 있음
-
장면 복잡도 확인
- 객체가 10개 미만: BVH 오버헤드로 약간 느릴 수 있음 (정상)
- 객체가 50개 이상: BVH로 2-10배 속도 향상 기대
- 매우 복잡한 장면: 초기 BVH 구축에 시간이 소요될 수 있음
-
렌더링 품질 확인
- Soft Shadow 샘플: 16개 (4x4) - 고품질이지만 느림
- 인터랙션 중: 자동으로 1 샘플로 감소 (v2.1.0 디바운싱)
-
시스템 리소스 확인
- CPU 사용률이 높은 다른 프로세스가 실행 중인지 확인
- 메모리가 부족하지 않은지 확인
A: v2.1.0의 BVH 구조는 추가 메모리를 사용합니다.
메모리 오버헤드:
- 객체당 약 80 bytes (BVH 트리 노드)
- 100개 객체: 약 8 KB 추가 메모리
- 1000개 객체: 약 80 KB 추가 메모리
이것은 정상입니다:
- 메모리를 속도로 교환하는 트레이드오프
- 대부분의 장면에서 메모리 증가는 무시할 수 있는 수준
- 성능 향상(2-10배)이 메모리 오버헤드를 상쇄
문제가 있다면:
- 장면의 객체 수를 줄이세요
- 메모리 누수가 없는지 valgrind로 확인하세요
A: BVH 관련 문제일 수 있습니다. 다음을 확인하세요:
해결 방법:
-
버전 확인
- miniRT v2.1.0 이상을 사용하고 있는지 확인
- 이전 버전의 BVH 버그는 v2.1.0에서 수정됨
-
장면 파일 검증
cat scenes/your_scene.rt
- 모든 객체가 올바른 형식인지 확인
- 카메라가 객체를 바라보는지 확인
- 광원이 장면을 비추는지 확인
-
간단한 장면으로 테스트
./miniRT scenes/test_simple.rt
- 간단한 장면이 정상 작동하면 복잡한 장면의 문제
- 간단한 장면도 검은 화면이면 설치 문제
-
BVH 경계 확인
- 매우 큰 객체나 먼 객체: AABB 계산 오버플로우 가능
- 객체를 카메라 근처로 이동해보세요
A: 이것은 v2.1.0의 디바운싱 기능이 정상 작동하는 것입니다.
디바운싱이란:
- 키 입력 후 150ms 동안 대기
- 추가 입력이 없으면 렌더링 시작
- 불필요한 렌더링 90% 이상 감소
사용자 경험:
- 카메라/객체를 움직일 때: 프리뷰 모드로 즉시 반응 (<100ms)
- 입력 멈춤 후 150ms: 최종 고품질 렌더링 시작
- 부드러운 인터랙션, 입력 지연 없음
이것은 의도된 동작입니다:
- 성능 최적화를 위한 디자인
- 프리뷰 모드가 즉각적인 피드백 제공
- 디바운싱 덕분에 시스템이 입력 버퍼링에서 해방됨
상세한 내용은 인터랙티브 컨트롤을 참조하세요.
A: 프리뷰 모드는 v2.1.0의 새 기능입니다.
확인 사항:
-
버전 확인
- miniRT v2.1.0 이상인지 확인
- HUD(H 키)에서 버전 확인 가능
-
프리뷰 설정 확인
- 프리뷰 모드는 기본 활성화
- 매우 간단한 장면: 프리뷰가 너무 빨라 눈에 안 보일 수 있음
-
동작 확인
- 카메라를 움직일 때 (W/A/S/D/Q/Z)
- 먼저 빠른 렌더링(프리뷰)이 나타남
- 그 다음 고품질 렌더링(최종)이 나타남
프리뷰 모드의 특징:
- <100ms 렌더링 시간 (일반적으로)
- 낮은 그림자 품질 (빠른 피드백용)
- 자동으로 최종 렌더로 업그레이드
A: BVH는 자동으로 활성화됩니다. 다음을 확인하세요:
- 객체 수: 50개 이상이면 초기 BVH 빌드에 시간이 걸립니다.
- 해상도: 800x600이 기본입니다.
- Soft Shadow: 인터랙션 중에는 자동으로 1 sample로 축소됩니다 (v2.1.0 디바운싱).
- 버전: v2.1.0 이상에서 최대 성능 향상을 경험할 수 있습니다.
A: Shadow Acne 현상입니다. 이미 적응형 Shadow Bias가 적용되어 있지만, 매우 얇은 객체에서는 발생할 수 있습니다.
A: 자기 교차(Self-intersection) 문제입니다. Shadow Bias가 충분하지 않을 수 있습니다.
A: 프리뷰 모드는 v2.1.0에 추가된 기능으로, 인터랙션 중 즉각적인 시각적 피드백을 제공합니다.
작동 방식:
- 카메라나 객체를 움직일 때
- 먼저 저품질 프리뷰 렌더링 (빠름, <100ms)
- 자동으로 고품질 최종 렌더링으로 전환
장점:
- 입력 지연 없는 즉각적인 반응
- 부드러운 인터랙션 경험
- 품질과 속도의 최적 균형
사용 방법:
- 별도 설정 불필요 (기본 활성화)
- 카메라 조작 시 자동 작동 (W/A/S/D/Q/Z/E/C)
- 객체 조작 시 자동 작동 (R/T/F/G/V/B)
상세한 내용은 인터랙티브 컨트롤을 참조하세요.
A: 현재 버전에서는 디바운싱이 기본적으로 활성화되어 있으며, 비활성화 옵션은 제공하지 않습니다.
이유:
- 디바운싱은 성능과 사용성을 크게 향상시킴
- 불필요한 렌더링 90% 이상 감소
- 입력 버퍼링 문제 해결
대안:
- 디바운싱 타이머는 150ms로 매우 짧음
- 프리뷰 모드가 즉각적인 피드백 제공
- 실제 사용 시 지연을 느끼기 어려움
A: v2.1.0에서 BVH는 항상 활성화되어 있으며, 비활성화할 수 없습니다.
이유:
- BVH는 성능을 크게 향상시킴 (2-10배)
- 간단한 장면에서도 오버헤드가 최소
- 복잡한 장면에서 필수적
성능 비교:
- BVH 없음: O(n) - 모든 객체 검사
- BVH 있음: O(log n) - 로그 시간 검색
A: 프리뷰 모드는 빠른 피드백을 위해 의도적으로 저품질로 설계되었습니다.
현재 동작:
- 프리뷰: 빠른 렌더링 (<100ms)
- 최종: 고품질 렌더링 (자동 전환)
품질 향상 방법:
- 프리뷰는 자동으로 최종 렌더로 업그레이드됨
- 입력을 멈추면 150ms 후 최종 렌더링 시작
- 인내심을 가지고 최종 렌더를 기다리세요
Last Updated: 2026-01
Version: 2.1.0