마우스 기기 지원 추가

다음 함수를 사용하여 게임 컨트롤러 라이브러리를 통해 게임에 마우스 기기 지원을 추가합니다. 여기에서는 마우스 기기라는 용어를 사용하여 기존의 마우스는 물론 트랙패드와 트랙볼을 설명할 수 있습니다.

마우스 상태 콜백 추가

게임 컨트롤러 라이브러리는 마우스 상태 콜백을 사용하여 마우스의 연결 또는 연결 해제 시 이를 게임에 알립니다. 한 번에 하나의 마우스 상태 콜백만 지원합니다.

  • 마우스 상태 콜백을 등록하거나 이전에 등록된 콜백을 새 콜백 함수로 바꾸려면 Paddleboat_setMouseStatusCallback 함수를 호출합니다.
  • 현재 등록된 콜백을 삭제하려면 statusCallback 매개변수의 NULL 또는 nullptr를 전달합니다.
  • userData 매개변수는 사용자 정의 데이터를 위한 선택적 포인터입니다. userData 매개변수는 콜백 함수에 전달됩니다. 이 포인터는 이후 Paddleboat_setMouseStatusCallback을 호출할 때까지 내부적으로 유지됩니다.
void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
  statusCallback, void *userData)

마우스 상태 콜백 함수의 함수 서명은 다음과 같습니다.

typedef void (*Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus
  mouseStatus, void *userData)

mouseStatus 열거형 매개변수에 사용 가능한 값은 세 가지입니다.

  • PADDLEBOAT_MOUSE_NONE: 현재 연결된 마우스 기기가 없습니다.
  • PADDLEBOAT_MOUSE_CONTROLLER_EMULATED: 연결된 컨트롤러가 마우스를 시뮬레이션합니다.
  • PADDLEBOAT_MOUSE_PHYSICAL: 하나 이상의 실제 마우스 기기가 연결되어 있습니다. (이러한 기기에는 마우스, 터치패드, 트랙볼 또는 기타 유사한 기기가 포함됩니다.)

userData 매개변수에는 Paddleboat_setMouseStatusCallback의 마지막 호출에서 지정된 userData 포인터가 포함됩니다. userData는 NULL 또는 nullptr일 수 있습니다.

일부 컨트롤러는 마우스를 시뮬레이션하지 않습니다. 컨트롤러는 아날로그 스틱 중 하나 또는 통합 터치패드를 사용하여 마우스를 시뮬레이션할 수 있습니다.

게임 컨트롤러 라이브러리는 단일 마우스 기기의 데이터만 보고합니다. 실제 마우스 기기는 가상 컨트롤러 마우스 기기보다 우선합니다. 실제 마우스가 연결되면 이전의 활성 가상 컨트롤러 마우스를 우선하여 마우스 역할을 합니다.

마우스 데이터 읽기

Paddleboat_getMouseStatus 함수를 호출하여 마우스 기기의 상태를 가져옵니다.

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

Paddleboat_getMouseData 함수를 사용하여 현재 마우스 데이터를 가져옵니다. 이 함수는 데이터를 성공적으로 읽으면 PADDLEBOAT_NO_ERROR를 반환하고, 그렇지 않으면 해당하는 오류 코드를 반환합니다.

bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

Paddleboat_Mouse_Data 구조에는 다음에 관한 정보가 포함됩니다.

  • 가장 최근의 마우스 입력 이벤트 타임스탬프
  • 현재 포인터 위치
  • 마우스 버튼 상태
  • 마우스 휠 상태
struct Paddleboat_Mouse_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    int32_t mouseScrollDeltaH;
    int32_t mouseScrollDeltaV;
    float mouseX;
    float mouseY;
}
구조 멤버 설명
timestamp 최신 마우스 입력 이벤트의 타임스탬프. 타임스탬프 값은 시계 에포크 이후의 마이크로초 단위입니다.
buttonsDown 비트필드. 0부터 시작하는 각 비트는 설정된 경우 버튼 다운 상태를 나타냅니다.
mouseX
mouseY 		마우스 위치(픽셀 좌표). 위치 좌표의 범위는 화면 너비와 높이에 대해 0.0입니다.
mouseScrollDeltaH
mouseScrollDeltaV 		이전 Paddleboat_getMouseData 호출 이후 누적 마우스 스크롤 휠 이벤트 횟수. 이 값은 정확성이 보장되지 않으며, 특정 방향의 스크롤 휠 활동을 나타내는 경우에만 유용합니다. 대부분의 마우스에는 한 개의 스크롤 휠이 있으며, 이는 mouseScrollDeltaV에 보고됩니다. 마우스에 사이드 스크롤 휠이 있는 경우 mouseScrollDeltaH에 보고됩니다. 이러한 값은 Paddleboat_getMouseData 호출 이후 내부적으로 0으로 재설정됩니다.

게임 컨트롤러 라이브러리는 paddleboat.h 인터페이스 헤더 파일의 마우스 버튼에 대한 비트마스크 상수를 정의합니다.

enum Paddleboat_Mouse_Buttons {
    PADDLEBOAT_MOUSE_BUTTON_LEFT = (1U << 0),
    PADDLEBOAT_MOUSE_BUTTON_RIGHT = (1U << 1),
    PADDLEBOAT_MOUSE_BUTTON_MIDDLE = (1U << 2),
    PADDLEBOAT_MOUSE_BUTTON_BACK = (1U << 3),
    PADDLEBOAT_MOUSE_BUTTON_FORWARD = (1U << 4),
    PADDLEBOAT_MOUSE_BUTTON_6 = (1U << 5),
    PADDLEBOAT_MOUSE_BUTTON_7 = (1U << 6),
    PADDLEBOAT_MOUSE_BUTTON_8 = (1U << 7)
};

실제 마우스와 가상 마우스 기기 비교

Paddleboat_MouseStatus가 PADDLEBOAT_MOUSE_CONTROLLER_EMULATED인 경우 실제 마우스 기기가 없고 게임 컨트롤러 라이브러리가 연결된 컨트롤러를 사용하여 가상 마우스를 시뮬레이션하고 있음을 나타냅니다. PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE 플래그가 설정된 가장 낮은 연결된 컨트롤러 색인은 가상 마우스로 사용됩니다. 가상 마우스 기기는 mouseX 및 mouseY 좌표만 보고할 수 있습니다. 가상 마우스 기기는 하나의(왼쪽) 마우스 버튼이 눌리는 것을 보고할 수 있지만 보장되지는 않습니다.