Release v2.3.0: HUD input optimization & debounce FSM redesign

Makefile

@@ -118,7 +118,6 @@ SRCS		= $(SRC_DIR)/main.c \
 			  $(SRC_DIR)/window/window_key_handlers.c \
 			  $(SRC_DIR)/window/window_loop.c \
 			  $(SRC_DIR)/window/window_camera.c \
-			  $(SRC_DIR)/window/window_selection.c \
 			  $(SRC_DIR)/window/window_objects.c \
 			  $(SRC_DIR)/window/window_resize.c \
 			  $(SRC_DIR)/window/window_rotate.c \

README.md

@@ -13,7 +13,7 @@ C로 작성한 실시간 인터랙티브 레이트레이서. BVH 가속 구조,
 - **조명**: Phong 모델 (ambient + diffuse + specular)
 - **그림자**: 하드/소프트 섀도우 (스토캐스틱 샘플링, offset LUT 사전 계산)
 - **BVH 가속 구조**: median split, plane 분리, any-hit shadow 가속
-- **인터랙티브 조작**: 카메라 이동/회전, 오브젝트 선택/이동, 광원 조정
+- **인터랙티브 조작**: 카메라 이동/회전, 오브젝트 선택/이동/리사이즈/회전, 광원 이동
 - **HUD 오버레이**: 씬 정보, 성능 메트릭, 키가이드
 
 ---
@@ -74,11 +74,14 @@ make
 | | Q / Z | 상승 / 하강 |
 | **카메라 회전** | E / C | 피치 위 / 아래 |
 | **카메라 리셋** | S | 초기 위치 복원 |
-| **오브젝트 선택** | \[ / \] | 이전 / 다음 |
+| **오브젝트 선택** | TAB | 다음 오브젝트 |
 | **오브젝트 이동** | R/T, F/G, V/B | X, Y, Z축 |
-| **광원 이동** | Ins/Del, Home/End, PgUp/PgDn | X, Y, Z축 |
+| **오브젝트 리사이즈** | Y/U | 반지름 -/+ |
+| | N/M | 높이 -/+ (원기둥) |
+| **오브젝트 회전** | I/J, O/K, P/L | X, Y, Z축 |
+| **광원 이동** | [ / ], ; / ', , / . | X, Y, Z축 |
 | **UI** | H | HUD 토글 |
-| | I | 성능 정보 토글 |
+| | Up / Down | HUD 페이지 이동 |
 | | ESC | 종료 |
 
 ---
@@ -161,6 +164,7 @@ miniRT/
 
 | 버전 | 날짜 | 주요 변경 |
 |------|------|----------|
+| v2.3.0 | 2026-02 | 디바운스 FSM 재설계, 키맵 재배치 (리사이즈/회전/광원), dead code 제거 |
 | v2.2.0 | 2026-02 | Plane BVH 분리, shadow BVH any-hit, 4라운드 성능 최적화 (S4 77.7%↑) |
 | v2.1.0 | 2026-01 | BVH 가속 기본 활성화, 디바운스 렌더링, BVH 시각화 |
 | v2.0.0 | 2026-01 | 코드 리팩토링, 모듈화 개선 |

docs/Architecture.md

@@ -15,13 +15,16 @@ main()
  ├── init_window()           # MiniLibX 윈도우/이미지/HUD 초기화
  └── mlx_loop()              # 이벤트 루프 진입
       └── render_loop()      # 매 프레임 콜백
-           ├── metrics_start_frame()
-           ├── render_scene_to_buffer()
-           │    ├── create_camera_ray()
-           │    ├── trace_ray()
-           │    └── put_pixel_to_buffer()
-           ├── mlx_put_image_to_window()
-           ├── metrics_end_frame()
+           ├── debounce_update()          # 디바운스 FSM 상태 전이
+           ├── rebuild_bvh_if_dirty()     # BVH 재구축 (필요 시)
+           ├── [RENDER_DIRTY] execute_render_pass()
+           │    ├── metrics_start_frame()
+           │    ├── render_scene_to_buffer()
+           │    │    ├── create_camera_ray()
+           │    │    ├── trace_ray()
+           │    │    └── put_pixel_to_buffer()
+           │    ├── metrics_end_frame()
+           │    └── mlx_put_image_to_window()
            ├── hud_render()
            └── keyguide_render()
 ```
@@ -95,9 +98,9 @@ trace_ray(scene, ray)
 
 ### 5. 디바운스
 
-입력 이벤트 발생 시 즉시 low quality 렌더링 후, 150ms 디바운스 타이머 경과 후 full quality 렌더링을 수행합니다.
+입력 이벤트 발생 시 디바운스 FSM이 LQ preview를 50ms 간격으로 트리거하고, 150ms 입력 없으면 full quality 렌더링을 수행합니다.
 
-상태 머신: `IDLE → ACTIVE → PREVIEW → FINAL`
+상태 머신: `IDLE → ACTIVE (150ms) → FINAL (FQ render) → COOLDOWN (350ms) → IDLE`
 
 ---
 
@@ -109,7 +112,7 @@ trace_ray(scene, ray)
 | render/ | 11 | 렌더 루프, 카메라, 메트릭 |
 | spatial/ | 8 | BVH 구축/순회, AABB |
 | lighting/ | 5 | Phong 조명, 그림자 |
-| hud/ | 14 | HUD 오버레이 |
+| hud/ | 15 | HUD 오버레이 |
 | window/ | 14 | 윈도우, 키 이벤트 |
 | ray/ | 2 | 교차 판정 |
 | math/ | 2 | 벡터 연산 |

docs/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-02
+
+### Added
+- **Object Resize**: Y/U 키로 반지름, N/M 키로 원기둥 높이 조절
+- **Object Rotation**: I/J (X축), O/K (Y축), P/L (Z축) Rodrigues 회전
+- **LQ Preview Throttle**: 디바운스 중 50ms 간격 low quality 프리뷰
+
+### Changed
+- **Debounce FSM Redesign**: 4-상태 머신 IDLE → ACTIVE (150ms) → FINAL → COOLDOWN (350ms)으로 단순화. PREVIEW 상태 제거
+- **Keymap Overhaul**: 광원 이동 키를 `[`/`]`/`;`/`'`/`,`/`.`으로 변경, 오브젝트 선택을 TAB으로 통일, HUD 페이지를 Up/Down으로 변경
+- **Render Flags**: `RENDER_SHOW_INFO`, `RENDER_SHIFT_HELD` 제거
+
+### Removed
+- **Dead Code Cleanup**: I 키 정보 토글 핸들러, shift 키 핸들링, 미사용 키 정의 (Insert, Home, PgUp, Delete, End, PgDn, Left, Right) 제거
+
 ## [2.2.0] - 2026-02
 
 ### Added
@@ -38,7 +53,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **BVH Acceleration**: 기본 활성화, 복잡한 씬에서 2~10배 렌더링 가속
-- **Debounced Rendering**: 150ms 디바운스 타이머, 4-상태 머신 (IDLE → ACTIVE → PREVIEW → FINAL)
+- **Debounced Rendering**: 150ms 디바운스 타이머 기반 렌더링 최적화
 - **BVH Tree Visualization**: `--bvh-vis` 플래그로 BVH 트리 구조 콘솔 출력
 - **Unified Object Identifiers**: 일관된 오브젝트 식별자 체계 (sp0, pl1, cy2)
 - `is_rendering` 플래그로 정확한 렌더 진행 추적

docs/Data-Structures.md

@@ -299,7 +299,16 @@ typedef struct s_render
 }   t_render;
 ```
 
-렌더 상태 플래그: `RENDER_DIRTY (0x01)`, `RENDER_RENDERING (0x02)`, `RENDER_LOW_QUALITY (0x04)` 등
+렌더 상태 플래그:
+
+| 플래그 | 값 | 설명 |
+|--------|------|------|
+| `RENDER_DIRTY` | 0x01 | 재렌더링 필요 |
+| `RENDER_RENDERING` | 0x02 | 렌더링 진행 중 |
+| `RENDER_LOW_QUALITY` | 0x04 | 저품질 프리뷰 모드 |
+| `RENDER_BVH_DIRTY` | 0x20 | BVH 재구축 필요 |
+| `RENDER_ENABLE_PIXEL_TIMING` | 0x40 | 픽셀 타이밍 측정 활성화 |
+| `RENDER_ENABLE_METRICS_PRINT` | 0x80 | 콘솔 메트릭 출력 활성화 |
 
 ---
 

docs/Module-HUD.md

@@ -16,7 +16,7 @@ HUD(Head-Up Display) 오버레이와 키가이드를 담당하는 모듈입니
 | `hud_objects.c` | 오브젝트 목록 페이지네이션 |
 | `hud_obj_render.c` | 개별 오브젝트 정보 렌더링 |
 | `hud_performance.c` | 성능 메트릭 (FPS, 렌더 시간, BVH 통계) |
-| `hud_text.c` | 텍스트 렌더링 유틸리티 |
+| `hud_text.c` | HUD dirty 마킹, vec3 포맷 출력 |
 | `hud_format.c` | 숫자/벡터 포맷팅 |
 | `hud_format_helpers.c` | 포맷 헬퍼 |
 | `hud_format_simple.c` | 간단한 포맷 유틸리티 |
@@ -109,5 +109,5 @@ typedef struct s_hud_state
 전체 페이지: 5
 현재 페이지: 1/5
 
-[ / ] 키로 페이지 이동
+Up / Down 키로 페이지 이동
 ```

docs/Module-Render.md

@@ -28,22 +28,25 @@
 
 ```
 render_loop(render)
- ├── metrics_start_frame()
- ├── render_scene_to_buffer(scene, render)
- │    ├── [full quality] render_pixel() per pixel
- │    │    ├── create_camera_ray()
- │    │    ├── get_time_ns()         // 시작 시간
- │    │    ├── trace_ray()
- │    │    ├── get_time_ns()         // 종료 시간
- │    │    ├── pixel_timing_add_sample()
- │    │    └── put_pixel_to_buffer()
- │    └── [low quality] render_low_quality()
- │         ├── create_camera_ray()
- │         ├── trace_ray()
- │         └── draw_pixel_block()   // 블록 단위 채우기
- ├── mlx_put_image_to_window()
- ├── metrics_end_frame()
- ├── hud_render()
+ ├── debounce_update()              // FSM 상태 전이
+ ├── rebuild_bvh_if_dirty()         // BVH 재구축 (필요 시)
+ ├── [RENDER_DIRTY] execute_render_pass()
+ │    ├── metrics_start_frame()
+ │    ├── render_scene_to_buffer(scene, render)
+ │    │    ├── [full quality] render_pixel() per pixel
+ │    │    │    ├── create_camera_ray()
+ │    │    │    ├── get_time_ns()         // 시작 시간
+ │    │    │    ├── trace_ray()
+ │    │    │    ├── get_time_ns()         // 종료 시간
+ │    │    │    ├── pixel_timing_add_sample()
+ │    │    │    └── put_pixel_to_buffer()
+ │    │    └── [low quality] render_low_quality()
+ │    │         ├── create_camera_ray()
+ │    │         ├── trace_ray()
+ │    │         └── draw_pixel_block()   // 블록 단위 채우기
+ │    ├── metrics_end_frame()
+ │    └── mlx_put_image_to_window()
+ ├── [HUD visible & dirty] hud_render()
  └── keyguide_render()
 ```
 
@@ -88,18 +91,20 @@ t_color trace_ray(t_scene *scene, t_ray *ray)
 
 ## 디바운스 메커니즘
 
-상태 머신:
+4-상태 FSM:
 
 ```
-IDLE ─(키 입력)─→ ACTIVE ─(low quality 렌더 완료)─→ PREVIEW
-  ↑                                                      │
-  └──────────────(150ms 경과, full render 완료)──── FINAL ←┘
+IDLE ─(입력)─→ ACTIVE ─(150ms 만료)─→ FINAL ─(FQ 렌더 완료)─→ COOLDOWN ─(350ms)─→ IDLE
+                 ↑                                                                    │
+                 └────────────────────────(재입력 시)──────────────────────────────────┘
 ```
 
 - **IDLE**: 대기 상태
-- **ACTIVE**: 키 입력 감지, low quality 렌더 수행
-- **PREVIEW**: low quality 결과 표시 중, 타이머 대기
-- **FINAL**: 타이머 만료 후 full quality 렌더, 완료 시 IDLE 복귀
+- **ACTIVE**: 입력 감지, 디바운스 타이머 시작 (150ms). LQ preview를 50ms throttle로 표시
+- **FINAL**: 타이머 만료, full quality 렌더 트리거 (`RENDER_LOW_QUALITY` 해제)
+- **COOLDOWN**: FQ 렌더 완료 후 350ms 쿨다운. 재입력 시 ACTIVE로 복귀
+
+LQ preview throttle: `debounce_check_preview_throttle()`로 50ms 간격 제한
 
 ---
 
@@ -117,4 +122,4 @@ IDLE ─(키 입력)─→ ACTIVE ─(low quality 렌더 완료)─→ PREVIEW
 | BVH | `nodes_visited` | 방문한 BVH 노드 수 |
 | | `tests_skipped` | AABB 스킵된 테스트 수 |
 
-메트릭은 HUD에 실시간 표시되며, I 키로 콘솔 출력을 토글할 수 있습니다.
+메트릭은 HUD에 실시간 표시됩니다. `RENDER_ENABLE_METRICS_PRINT` 플래그 설정 시 콘솔에도 출력됩니다.

docs/Module-Window.md

@@ -78,8 +78,7 @@ init_window(scene)
 ### 오브젝트 선택
 | 키 | 동작 |
 |----|------|
-| \[ | 이전 오브젝트 |
-| \] | 다음 오브젝트 |
+| TAB | 다음 오브젝트 |
 
 ### 오브젝트 이동
 | 키 | 축 | 방향 |
@@ -91,21 +90,36 @@ init_window(scene)
 | V | Z | - |
 | B | Z | + |
 
+### 오브젝트 리사이즈
+| 키 | 대상 | 방향 |
+|----|------|------|
+| Y | 반지름 | - |
+| U | 반지름 | + |
+| N | 높이 (원기둥) | - |
+| M | 높이 (원기둥) | + |
+
+### 오브젝트 회전
+| 키 | 축 | 방향 |
+|----|------|------|
+| I / J | X | - / + |
+| O / K | Y | - / + |
+| P / L | Z | - / + |
+
 ### 광원 이동
 | 키 | 축 | 방향 |
 |----|----|------|
-| Insert | X | - |
-| Delete | X | + |
-| Home | Y | - |
-| End | Y | + |
-| PageUp | Z | - |
-| PageDown | Z | + |
+| \[ | X | - |
+| \] | X | + |
+| ; | Y | - |
+| ' | Y | + |
+| , | Z | - |
+| . | Z | + |
 
 ### UI
 | 키 | 동작 |
 |----|------|
 | H | HUD 표시/숨김 |
-| I | 성능 메트릭 토글 |
+| Up / Down | HUD 페이지 이동 |
 | ESC | 프로그램 종료 |
 
 ---
@@ -115,16 +129,19 @@ init_window(scene)
 ```
 handle_key(keycode, render)
  ├── ESC → close_window()
- ├── H/I → handle_hud_keys()
- ├── [ / ] → handle_object_selection()
+ ├── H/TAB/Up/Down → handle_hud_keys()
  ├── W/X/A/D/Q/Z/E/C/S → handle_camera_keys()
- └── R/T/F/G/V/B/Ins/Del/... → handle_transform_keys()
+ └── R/T/F/G/V/B/[/]/;/'/,/./Y/U/N/M/I/J/O/K/P/L → handle_transform_keys()
+      ├── R/T/F/G/V/B → handle_object_move()
+      ├── [/]/;/'/,/. → handle_light_move()
+      ├── Y/U/N/M → handle_object_resize()
+      └── I/J/O/K/P/L → handle_object_rotate()
 
 handle_key_release(keycode, render)
- └── is_movement_key() → 디바운스 full render 트리거
+ └── (no-op)
 ```
 
-키 누름 시 `RENDER_DIRTY` + `RENDER_LOW_QUALITY` 플래그를 설정하여 즉시 low quality 렌더링을 수행하고, 키 해제 시 디바운스 타이머를 시작합니다.
+키 누름 시 디바운스 FSM이 LQ preview를 트리거하고 (50ms throttle), 150ms 입력 없으면 full quality 렌더링을 수행합니다.
 
 ---
 

includes/hud.h

@@ -287,12 +287,6 @@ void	hud_format_bvh_status(char *buf, int enabled);
 */
 void	hud_render_performance(t_render *render, int *y);
 
-/*
-** Render HUD background overlay (semi-transparent dark rectangle).
-** Called internally by hud_render().
-*/
-void	hud_render_background(t_render *render);
-
 /*
 ** Render HUD text content (camera, lights, objects).
 ** Called internally by hud_render().

includes/hud_text.h

@@ -16,8 +16,6 @@
 # include "minirt.h"
 
 void	hud_mark_dirty(t_render *render);
-void	hud_render_background_row(t_render *render, int y);
-void	hud_render_background(t_render *render);
 void	format_and_print_vec3(t_render *render, int *y,
 			char *label, t_vec3 vec);
 int		copy_str_to_buf(char *dst, char *src);

includes/render_debounce.h

@@ -16,9 +16,9 @@
 # include <sys/time.h>
 
 /* Default configuration values */
-# define DEBOUNCE_DEFAULT_DELAY_MS		150
-# define DEBOUNCE_DEFAULT_PREVIEW		1
-# define DEBOUNCE_DEFAULT_AUTO_UPGRADE	1
+# define DEBOUNCE_DEFAULT_DELAY_MS			150
+# define DEBOUNCE_COOLDOWN_MS				350
+# define DEBOUNCE_PREVIEW_MIN_INTERVAL_MS	50
 
 /* Forward declaration */
 typedef struct s_render	t_render;
@@ -28,8 +28,8 @@ typedef enum e_debounce_state_enum
 {
 	DEBOUNCE_IDLE,
 	DEBOUNCE_ACTIVE,
-	DEBOUNCE_PREVIEW,
-	DEBOUNCE_FINAL
+	DEBOUNCE_FINAL,
+	DEBOUNCE_COOLDOWN
 }	t_debounce_state_enum;
 
 /* Debounce timer for tracking input delay */
@@ -45,9 +45,7 @@ typedef struct s_debounce_state
 {
 	t_debounce_state_enum	state;
 	t_debounce_timer		timer;
-	int						preview_enabled;
-	int						auto_upgrade;
-	int						cancel_requested;
+	struct timeval			last_preview_time;
 }	t_debounce_state;
 
 /* Initialization and cleanup */
@@ -59,13 +57,11 @@ void	debounce_on_input(t_debounce_state *state, t_render *render);
 /* State machine update */
 void	debounce_update(t_debounce_state *state, t_render *render);
 
-/* Render cancellation */
-void	debounce_cancel(t_debounce_state *state);
-
 /* Timer utilities */
 void	debounce_timer_start(t_debounce_timer *timer);
 void	debounce_timer_reset(t_debounce_timer *timer);
 void	debounce_timer_stop(t_debounce_timer *timer);
 int		debounce_timer_expired(t_debounce_timer *timer);
+int		debounce_check_preview_throttle(t_debounce_state *state);
 
 #endif

includes/window.h

@@ -29,8 +29,6 @@
 # define RENDER_DIRTY       0x01
 # define RENDER_RENDERING   0x02
 # define RENDER_LOW_QUALITY 0x04
-# define RENDER_SHIFT_HELD  0x08
-# define RENDER_SHOW_INFO  0x10
 # define RENDER_BVH_DIRTY  0x20
 # define RENDER_ENABLE_PIXEL_TIMING  0x40
 # define RENDER_ENABLE_METRICS_PRINT 0x80
@@ -58,6 +56,7 @@ typedef struct s_keyguide_state
 	int		visible;
 	int		x;
 	int		y;
+	int		dirty;
 }	t_keyguide_state;
 
 /* Render context (refactored with legacy compatibility) */