LampArray 기본 사항
이 페이지에서는 LampArray 콜백을 등록하고 ILampArray 및 ILampInfo 인스턴스와 상호 작용하는 방법을 설명합니다.
참고: 2023년 3월 복구 기준으로 GDK 조명 API는 콘솔에서 다음 장치만 지원합니다. 추가 디바이스에 대한 지원은 향후 복구 릴리스에서 추가될 예정입니다.
- Xbox One용 Razer Turret(키보드 및 마우스)
- Razer BlackWidow 토너먼트 에디션 Chroma V2
ILampArray 및 ILampInfo
시스템에 연결된 호환되는 각 조명 디바이스는 ILampArray 인스턴스로 표시됩니다. ILampArray는 크기, 디바이스 유형, 제조업체 및 램프 수와 같은 디바이스에 대한 정보를 제공합니다. 또한 램프의 밝기 및 색 값을 변경하는 메서드를 노출합니다.
ILampInfo 개체는 Lamp의 상대 위치, 색 지원 및 용도를 포함하여 LampArray의 개별 램프 속성을 캡슐화합니다. ILampArray::GetLampInfo를 사용하여 ILampInfo 인스턴스를 검색할 수 있습니다.
참고: 그래픽, 오디오 및 GameInput API와 마찬가지로 ILampArray 및 ILampInfo는 IUnknown에서 파생된 인터페이스를 노출하더라도 진정한 COM API가 아닙니다. 이 스타일의 API는 "COM lite" 또는 "nano-COM"이라고도 합니다. IUnknown은 참조 카운팅 및 리플렉션에 사용되지만 COM 런타임 인프라는 ILampArray 또는 ILampInfo에서 사용되지 않습니다. 특히, 이는 다음을 의미합니다.
- 애플리케이션은 개체 인스턴스를 얻기 위해
CoInitialize또는CoCreateInstance을(를) 호출하지 않습니다.- 집계 및 호출자 제공 인터페이스 구현과 같은 COM 기능이 지원되지 않습니다.
- 교차 프로세스 마샬링 지원도 없고 아파트/스레딩 모델도 없습니다. 모든 개체가 Agile입니다.
- 인터페이스 포인터는 IUnknown을 통과하지 않고 개체 ID를 대상으로 직접 비교할 수 있습니다.
- 메서드가
HRESULT코드를 반환할 필요가 없어 흔히 함수 서명이 간단해집니다.
LampArray 콜백
LampArray 콜백은 ILampArray 인스턴스를 가져오고 LampArrays가 시스템에서 연결되거나 제거될 때 알림을 받는 메커니즘입니다.
typedef interface ILampArray ILampArray;
typedef uint64_t LampArrayCallbackToken;
typedef void (CALLBACK * LampArrayCallback)(
_In_opt_ void * context,
bool isAttached,
_In_ ILampArray * lampArray);
HRESULT RegisterLampArrayCallback(
_In_ LampArrayCallback lampArrayCallback,
_In_opt_ void* context,
_Out_ _Result_zeroonfailure_ LampArrayCallbackToken* callbackToken);
콜백 스레딩
콜백이 등록될 때 LampArray 장치가 연결된 경우 RegisterLampArrayCallback 함수는 연결된 각 장치에 대해 해당 콜백이 호출될 때까지 차단됩니다(콜백이 호출 스레드에서 호출됨을 의미).
첫 번째 콜백이 등록되면 LampArray API는 작업자 스레드를 시작하여 ILampArray 장치 연결 및 제거 알림을 처리합니다. 이러한 이벤트는 자주 발생하지 않으며 작업자 스레드는 그렇지 않으면 대기 상태로 유지됩니다. 등록 호출이 반환된 후 모든 후속 LampArrayCallbacks는 이 작업자 스레드에서 순차적으로 호출됩니다.
LampArray 작업자 스레드에 대한 프로세서 선호도는 TrySetLampArrayWorkerThreadAffinityMask를 사용하여 제어할 수 있습니다. 이 API는 프로세스당 최대 한 번 호출할 수 있습니다. API에 대한 후속 호출은 적용되지 않습니다.
HRESULT TrySetLampArrayWorkerThreadAffinityMask(
uint64_t threadAffinityMask);
콜백 등록 취소
콜백이 성공적으로 등록되면 응용 프로그램은 콜백을 실행하는 데 필요한 모든 리소스가 유효한 상태로 유지되도록 해야 합니다. 여기에는 콜백 코드와 콜백 함수 자체가 사용하는 리소스가 모두 포함됩니다. 예를 들어 콜백 함수가 DLL에서 호스팅되어 응용 프로그램이 요청에 따라 로드되고 언로드되는 경우입니다.
이러한 리소스를 안전하게 회수하려면 애플리케이션이 먼저 RegisterLampArrayCallback 메서드에서 받은 토큰을 UnregisterLampArrayCallback 메서드에 전달하여 콜백 등록을 취소해야 합니다. 등록된 LampArray 콜백 내에서 LampArray 콜백을 등록 취소하는 것은 지원되지 않으며, 이렇게 시도하면 프로세스가 종료됩니다.
bool UnregisterLampArrayCallback(
LampArrayCallbackToken callbackToken,
uint64_t timeoutInMicroseconds);