> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PIXScopedEvent overview

> PIXScopedEvent overview

# PIXScopedEvent overview

Performance Investigator for XBOX(PIX)의 **Timing Capture** 기능에 표시할, CPU 활동 또는 XBOX 전용의 경우 GPU 활동의 컨텍스트별 타이밍 캡처를 위한 사용자 정의 이벤트를 생성합니다.

<a id="syntaxSection" />

## Syntax

```cpp theme={null}
void PIXScopedEvent(
         void* context,
         UINT64 color,
         _In_ PCWSTR formatString,
         ...
)
```

<a id="parametersSection" />

### Parameters

*context*   \
Type: void\*

이벤트의 컨텍스트입니다. XBOX 전용에서 이 매개 변수는 GPU 활동의 타이밍 캡처를 허용하기 위해 `ID3D12GraphicsCommandList*`, `ID3D12GraphicsCommandList*` 및 `ID3D12XboxDmaCommandList*` 포인터도 허용합니다.

*color*   \
Type: UINT64

타임라인 차트에 사용할 이벤트 색상입니다. 미리 정의된 색상을 사용하려면 [PIX\_COLOR](/reference/tools/pix3/functions/pix_color) 상수를 지정하고, 색상 인덱스를 사용하려면 [PIX\_COLOR\_INDEX](/reference/tools/pix3/functions/pix_color_index) 상수를 지정하거나, 사용자 지정 색상을 사용하려면 ARGB 형식의 DWORD 값을 지정합니다. ARGB 형식의 DWORD 값을 지정하는 경우 해당 값의 알파 채널을 `0xff`로 설정해야 합니다.

*formatString*   \_In\_\
Type: PCWSTR

이벤트를 설명하는 데 사용할 이름으로, null로 종료되는 유니코드 문자열에 대한 포인터입니다. 문자열에는 `sprintf` 형식과 매우 유사한 선택적 문자열 형식 자리 표시자를 0개 이상 지정할 수 있습니다. 이 메서드는 최대 16개의 자리 표시자를 지원합니다.

Type: ...

*formatString*에 자리 표시자가 지정된 경우 이 매개 변수에 그에 상응하는 개수의 값을 지정해야 합니다. 이 매개 변수에 지정되는 값의 형식은 이에 대응하는 자리 표시자에 의해 식별되는 형식에 따라 다릅니다.

<a id="retvalSection" />

### Return value

Type: void

없음.

## Remarks

이 함수는 PIX의 **Timing Capture** 기능에 표시할, CPU 활동의 타이밍 캡처를 위한 사용자 정의 이벤트를 생성합니다. `PIXScopedEvent`로 생성된 이벤트는 API가 호출된 범위가 종료될 때 자동으로 끝나므로 이벤트의 시작과 끝을 자동으로 매칭할 수 있습니다.

`PIXScopedEvent` 함수는 런타임에 문자열을 형식화하는 대신 형식 문자열과 형식 매개 변수를 저장합니다. 그런 다음 PIX에서 캡처 파일을 읽을 때 형식화가 수행됩니다. 최상의 성능을 얻으려면 `PIXScopedEvent`에 8바이트로 정렬된 문자열 또는 가급적 16바이트로 정렬된 문자열을 사용합니다. `%p` 형식 지정자를 사용하여 `char\*` 또는 `wchar_t\*`를 포인터로 형식화하려면, 포인터를 `PIXScopedEvent`에 전달할 때 `void\*` 또는 정수형이나 부동 소수점 형식으로 캐스팅합니다.

`PIXScopedEvent` 호출에는 형식 문자열과 모든 변수의 전체 크기 및 정렬을 포함하는 레코드 데이터를 저장할 수 있도록 최소 512바이트의 공간이 보장됩니다. 일반적으로 PIX 이벤트는 게임의 주요 구성 요소, 시스템 또는 콘텐츠에 맞춰진 짧은 고성능 마커를 위한 것입니다.

이 메서드는 일반적으로 CPU 이벤트의 시간을 측정하는 데 사용됩니다. 그러나 `context` 매개 변수에 `ID3D12GraphicsCommandList*`, `ID3D12CommandQueue*` 또는 `ID3D12XboxDmaCommandList*` 포인터를 전달하면 GPU 이벤트의 시간도 측정할 수 있습니다.

<a id="requirementsSection" />

## Requirements

**Header:** pix3.h

**Library:** pixevt.lib

**Supported Platforms**: XBOX One 계열 콘솔 및 XBOX Series 콘솔

<a id="seealsoSection" />

## See also

[PIXScopedEvent](/reference/tools/pix3/functions/pixscopedevent-overloads)\
[PIX3](/reference/tools/pix3/pix3_members)\
[PIX (NDA topic)](/tools/tools-console/pix/pix)


## Related topics

- [PIXScopedEvent](/ko/reference/tools/pix3/functions/pixscopedevent-overloads.md)
- [PIXScopedEvent function](/ko/reference/tools/pix3/functions/pixscopedevent.md)
- [PIXScopedEvent reference](/ko/reference/tools/pix3/functions/pixscopedevent_2.md)
- [PIXScopedEvent function reference](/ko/reference/tools/pix3/functions/pixscopedevent_3.md)
- [PIX_COLOR](/ko/reference/tools/pix3/functions/pix_color.md)