SDL 3.4.20, Windows 상대 마우스 모드에서 휠 방향 수정

일반 커서와 상대 마우스 모드는 같은 조건이 아닙니다

SDL 3.4.20은 한국시간 2026년 11월 4일 공개된 안정판 버그 수정 릴리스입니다. Windows 상대 마우스 모드에서 휠 방향이 잘못 처리되던 문제를 수정했습니다. Wayland 클립보드 처리와 X11 컬러 커서의 알파 마스크 등 다른 플랫폼의 수정도 포함하지만, 게임 카메라와 연결되는 핵심 항목은 상대 모드의 입력 방향입니다.

SDL 공식 API 문서에서 상대 모드는 창에 포커스가 있을 때 커서를 숨기고 이동 범위를 창 안으로 제한하면서, 창 가장자리에서도 연속적인 상대 이동을 보고하는 방식입니다. 커서를 반드시 화면 중앙에 고정한다는 뜻은 아닙니다. 위치를 별도로 제한하려면 SDL_SetWindowMouseRect 같은 기능을 함께 검토해야 합니다. 기존 글의 ‘중앙에 고정한 채 읽는다’는 표현보다 API의 실제 보장을 기준으로 이해하는 편이 정확합니다.

휠 이벤트의 값과 방향을 같이 봐야 합니다

SDL_MouseWheelEvent에는 가로·세로 스크롤 값인 x와 y, 그리고 방향을 나타내는 direction이 있습니다. 문서는 y의 양수가 사용자에게서 멀어지는 방향이고 음수가 사용자 쪽이라고 설명합니다. direction이 SDL_MOUSEWHEEL_FLIPPED이면 x·y가 반대이므로 필요에 따라 부호를 바꿔 해석합니다.

게임에서 휠을 무기 선택이나 줌에 연결했다면 메뉴의 스크롤이 정상이라는 사실만으로 수정 여부를 확인할 수 없습니다. 같은 물리적 휠 조작을 일반 모드와 상대 모드에서 각각 수행하고, 원래 이벤트 값과 게임에 적용된 동작을 함께 기록하면 라이브러리 입력과 게임의 바인딩을 구분할 수 있습니다. 기존 임시 보정 코드가 있다면 업데이트 뒤에도 필요한지 따로 확인해야 합니다.

모드 전환과 플랫폼별 회귀를 나눠 확인하세요

SDL_SetWindowRelativeMouseMode는 성공 여부를 bool로 반환하며 실패 정보는 SDL_GetError로 확인합니다. 문서상 메인 스레드에서 호출해야 하고, 해당 창에 대기 중인 마우스 이동 이벤트를 비웁니다. 일시 정지 메뉴에서 모드를 바꾸거나 창 포커스를 잃었다가 복귀하는 흐름을 검사할 때 이 조건도 고려할 필요가 있습니다.

같은 버전에는 Vulkan 텍스처 메모리 바인딩 실패 시 충돌, Android 10의 float 오디오 녹음 충돌, 일부 컨트롤러 처리 수정도 들어 있습니다. 그렇다고 휠 방향을 확인한 테스트가 이 항목까지 검증하는 것은 아닙니다. 프로젝트가 실제 사용하는 플랫폼과 입력 경로에 맞춰 테스트를 분리해야 합니다. 위 비교 절차는 공식 API에 근거한 회귀 점검 제안이며, 이 글에서 실행해 얻은 성능 수치는 아닙니다.

출처

• SDL 3.4.20 공식 릴리스 노트
• SDL 공식 API · SDL_SetWindowRelativeMouseMode
• SDL 공식 이벤트 문서 · SDL_MouseWheelEvent