포인터 잠금 2.0

Element 인터페이스는 포인터를 잠그는 기능을 요청할 수 있도록 확장되었습니다.

WebIDLpartial interface Element {
  Promise<undefined> requestPointerLock(optional PointerLockOptions options = {});
};

const lock_element = document.getElementById("lock_element");
const lock_button = document.getElementById("lock");
lock_button.addEventListener("click", async (event) => {
    try {
        await lock_element.requestPointerLock({ unadjustedMovement: true });
        console.log("성공적으로 잠금됨!");
    } catch (e) {
        console.log("잠금 실패, 에러: ", e);
    }
});

requestPointerLock(PointerLockOptions options) 메서드

lock requests queue라는 이름의 병렬 큐를 사용하여 모든 요청을 큐에 저장합니다. requestPointerLock() 호출 시 다음 단계를 수행합니다:

1. promise를 새로운 promise로 생성합니다.
2. 어떤 window 가 포커스 상태일 때, this의 shadow-including root 가 활성 문서의 탐색 컨텍스트(또는 조상 탐색 컨텍스트)가 포커스되어 있지 않으면:
   1. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
      1. pointerlockerror 이벤트를 this의 노드 문서에 발생시킵니다.
      2. promise를 Reject시키며 "WrongDocumentError" DOMException을 전달합니다.
   2. promise를 반환합니다.
   Issue 93: 가시성 상태 확인

   명세는 숨겨진 문서가 포인터 잠금을 요청하지 못하도록 해야 합니다.

   또한 문서가 숨겨지면 포인터 잠금을 해제해야 합니다.

3. 관련 전역 객체에 일시적 활성화가 없고 Document가 exitPointerLock() 호출로 성공적으로 포인터 잠금을 해제한 적이 없다면:
   1. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
      1. pointerlockerror 이벤트를 this의 노드 문서에 발생시킵니다.
      2. promise를 Reject시키며 "NotAllowedError" DOMException을 전달합니다.
   2. promise를 반환합니다.
   참고
4. this의 노드 문서의 활성 샌드박싱 플래그 세트에 샌드박스 포인터 잠금 탐색 컨텍스트 플래그가 설정되어 있다면:
   1. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
      1. pointerlockerror 이벤트를 this의 노드 문서에 발생시킵니다.
      2. promise를 Reject시키며 "SecurityError" DOMException을 전달합니다.
   2. promise를 반환합니다.
5. options["unadjustedMovement"] 값이 true이고, 플랫폼에서 unadjustedMovement를 지원하지 않으면:
   1. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
      1. pointerlockerror 이벤트를 this의 노드 문서에 발생시킵니다.
      2. promise를 Reject시키며 "NotSupportedError" DOMException을 전달합니다.
   2. promise를 반환합니다.
   Issue 90: `unadjustedMovement` 지원 여부를 나타내는 static 필드 제안

   PR #49에서 PointerLockOptions가 도입되었습니다. 하지만 PointerLockOptions의 unadjustedMovement가 모든 플랫폼에서 지원되지 않을 수 있습니다. 직접 사용하기 전에 지원 여부를 확인할 수 있도록 static 필드가 유용할 수 있습니다.

6. lock requests queue에 다음 단계를 큐에 추가합니다:
   1. 사용자 에이전트의 pointer-lock target 이 shadow-including root가 this의 shadow-including root와 다르다면:
      1. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
         1. pointerlockerror 이벤트를 this의 노드 문서에 발생시킵니다.
         2. promise를 Reject시키며 "InvalidStateError" DOMException을 전달합니다.
   2. 사용자 에이전트의 pointer-lock target의 shadow-including root가 this의 shadow-including root와 같고, options가 현재 pointer-lock options와 동일하다면:
      1. pointer-lock target을 this로 설정합니다.
      2. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
         1. pointerlockchange 이벤트를 this의 노드 문서에 발생시킵니다.
         2. promise를 Resolve합니다.
   3. pointer-lock target이 null이거나, options가 현재 pointer-lock options와 동일하지 않으면, lock 요청을 처리하고 완료 시 응답을 처리:
      1. lock 요청이 실패한 경우:
         1. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
            1. pointerlockerror 이벤트를 this의 노드 문서에 발생시킵니다.
            2. promise를 Reject시키며 "NotSupportedError" DOMException을 전달합니다.
         Issue 91: 후속 requestPointerLock이 거부될 때, 이미 잠금된 대상이 잠금 상태를 해제해야 하는가?

         PR #49의 requestPointerLock 알고리즘에서, 후속 요청이 어떤 이유로든 실패할 때, 이미 잠금된 대상이 잠금 상태를 해제해야 하는지 설명이 없습니다.

      2. lock 요청이 성공한 경우:
         1. pointer lock 상태로 진입하며, 다음을 수행:
            1. 사용자 에이전트의 pointer-lock target을 this로 설정합니다.
            2. 사용자 에이전트의 커서 위치를 현재 시스템 마우스 위치로 설정합니다.
            3. pointer-lock options를 options로 설정합니다.
         2. 요소 작업을 큐에 추가하여, 사용자 상호작용 작업 소스에서 this를 대상으로 다음 단계를 수행:
            1. pointerlockchange 이벤트를 this의 노드 문서에 발생시킵니다.
            2. promise를 Resolve합니다.
   Issue 96: lock requests queue 처리 미완성

   PR #49의 requestPointerLock 알고리즘에서, lock requests queue의 항목 처리에 대한 설명이 없습니다. 명시적 설명이 없으면 모든 항목이 동기적으로 큐에서 제거된다는 잘못된(?) 가정이 남을 수 있습니다.

7. promise를 반환합니다.

참고

WebIDLpartial interface Document {
  attribute EventHandler onpointerlockchange;
  attribute EventHandler onpointerlockerror;
  undefined exitPointerLock();
};

onpointerlockchange 속성

이벤트 핸들러 IDL 속성으로, pointerlockchange 이벤트를 처리합니다.

onpointerlockerror 속성

이벤트 핸들러 IDL 속성으로, pointerlockerror 이벤트를 처리합니다.

exitPointerLock() 메서드

1. 사용자 에이전트의 pointer-lock target이 null이면 반환합니다.
2. pointer-lock target의 shadow-including root가 this의 노드 문서와 다르면 반환합니다.
3. 사용자 에이전트의 pointer-lock target을 사용하여 포인터 잠금 해제를 수행합니다.

WebIDLpartial interface mixin DocumentOrShadowRoot {
  readonly attribute Element? pointerLockElement;
};

pointerLockElement

포인터가 잠긴 동안, 해당 요소를 재타겟팅한 결과를 반환합니다. 이 재타겟팅된 요소가 마우스 이벤트의 대상이 되며, this 요소와 같은 트리에 속해 있다면 그 결과 요소를, 아니라면 null을 반환합니다.

lock이 대기 중이거나 포인터가 잠금 해제 상태라면 null을 반환합니다.

예시 2

<body>
  <div id="host1">
    <shadow-root id="root1">
      <canvas id="canvas1"></canvas>
    </shadow-root>
  </div>
  <div id="host2">
    <shadow-root id="root2">
      <canvas id="canvas2"></canvas>
    </shadow-root>
  </div>
</body>

참고

예시에서는 가상의 shadow-root 요소를 사용하여 shadow root 인스턴스를 표현합니다.

#canvas1이 대상일 때 document.pointerLockElement는 #host1를, root1.pointerLockElement는 #canvas1을 반환합니다. 재타겟팅 결과 #canvas1을 #root2에 대해 재타겟팅하면 #host1가 되지만, #host1이 #root2와 같은 트리에 속하지 않으므로 root2.pointerLockElement는 null을 반환합니다.

WebIDLpartial interface MouseEvent {
  readonly attribute double movementX;
  readonly attribute double movementY;
};

movementX 속성

movementY 속성

movementX와 movementY 속성은 포인터 위치가 변화한 값을 제공합니다. 두 mousemove 이벤트 eNow와 ePrevious 사이에 screenX, screenY 값을 저장하고, movementX = eNow.screenX - ePrevious.screenX과 같이 차이를 계산하는 것과 같습니다.

movementX와 movementY는 mousemove 이벤트를 제외한 모든 마우스 이벤트에서는 0이어야 합니다. 모든 움직임 데이터는 mousemove 이벤트로 전달되어야 하며, 두 마우스 이벤트 earlierEvent와 currentEvent 사이의 currentEvent.screenX - earlierEvent.screenX 값은 earlierEvent 이후 이벤트들의 movementX 합계와 같아야 합니다(단, 포인터가 사용자 에이전트 화면 경계에 의해 클립되어 screenX를 갱신하지 못하는 경우는 예외).

movementX와 movementY는 포인터 잠금 상태와 관계없이 항상 갱신되어야 합니다.

잠금 해제 상태에서는 시스템 커서가 사용자 에이전트 창을 나갔다가 다시 진입할 수 있습니다. 이 경우 운영체제의 마우스 이동 이벤트의 대상이 사용자 에이전트가 아니면, 가장 최근의 포인터 위치를 사용자 에이전트가 알 수 없어 movementX / movementY 값을 계산할 수 없으므로 0으로 설정해야 합니다.

포인터 잠금이 활성화되면 clientX, clientY, screenX, screenY는 포인터가 전혀 움직이지 않은 것처럼 일정한 값을 유지해야 합니다. 하지만 movementX와 movementY는 잠금 해제 상태와 동일하게 포인터 이동 변화를 계속 제공해야 하며, 마우스를 한 방향으로 계속 이동하면 movementX와 movementY 값에 제한이 없습니다. 마우스 커서 개념이 제거되어 창을 벗어나거나 화면 경계에 의해 클램프되지 않습니다.

movementX와 movementY의 초기화되지 않은 값은 0이어야 합니다.

마우스 입력이 중단되는 상황(예: 마우스 커서가 창을 나갔다가 다른 위치로 다시 진입)에서는 큰 movement 값이 나타나면 안 됩니다. 사용자 에이전트가 운영체제에서 마우스 입력 데이터를 받지 못하는 간격이 생기면, 다음 mousemove 이벤트는 movementX와 movementY를 0으로 설정해야 합니다. 이러한 간격은 사용자 에이전트가 창 시스템 API에서 마우스 이탈 이벤트를 받을 때 등 발생할 수 있습니다. 예외적으로 마우스 캡처가 활성화되면 커서가 창 밖으로 이동해도 사용자 에이전트가 계속 마우스 이벤트를 받을 수 있습니다.

WebIDLpartial dictionary MouseEventInit {
  double movementX = 0;
  double movementY = 0;
};

movementX 멤버

movementY 멤버

movementX와 movementY 멤버는 각각 MouseEvent의 해당 멤버를 초기화하는 데 사용됩니다.

기본 잠금 해제 제스처는 항상 제공되어야 하며, 포인터 잠금 해제를 사용자 에이전트의 포인터-잠금 대상과 함께 수행해야 합니다.

포인터-잠금 대상이 연결 해제되거나, 사용자 에이전트, 윈도우, 탭이 포커스를 잃으면 포인터 잠금은 해제되어야 합니다. 활성 문서(active document)의 요소들 사이, 또는 탐색 컨텍스트 사이로 포커스를 이동하는 것은 포인터 잠금 해제를 일으키지 않습니다. 예를 들어, 키보드로 프레임이나 iframe 내의 콘텐츠 사이로 포커스를 이동해도 해제되지 않습니다.

전체 화면 [FULLSCREEN]이 진입하거나 해제될 때, 포인터가 사용자 에이전트의 그래픽 UI와 상호작용해야 하거나, 기본 잠금 해제 제스처로 전체 화면과 포인터 잠금을 동시에 해제하거나, 윈도우나 탭 포커스를 잃은 경우를 제외하고 포인터 잠금이 해제되어서는 안 됩니다.

비규범적으로 표시된 섹션뿐만 아니라, 이 명세서의 모든 작성 지침, 다이어그램, 예시, 참고 사항은 비규범적입니다. 그 외 모든 내용은 규범적입니다.

이 명세서는 하나의 제품에 적용되는 준수 기준을 정의합니다: 해당 명세서에 포함된 인터페이스를 구현하는 사용자 에이전트입니다.