> ## 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.

# Visão geral de PIXScopedEvent

> Visão geral de PIXScopedEvent

# Visão geral de PIXScopedEvent

Cria um evento definido pelo usuário para uma captura de tempo específica de contexto da atividade da CPU ou, somente no XBOX, da atividade da GPU, a ser exibido no recurso **Timing Capture** do Performance Investigator for XBOX (PIX).

<a id="syntaxSection" />

## Sintaxe

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

<a id="parametersSection" />

### Parâmetros

*context*   \
Tipo: void\*

O contexto do evento. Somente no XBOX, este parâmetro também aceita ponteiros `ID3D12GraphicsCommandList*`, `ID3D12GraphicsCommandList*` e `ID3D12XboxDmaCommandList*`, para permitir capturas de tempo da atividade da GPU.

*color*   \
Tipo: UINT64

A cor do evento a ser usada no gráfico de linha do tempo. Especifique uma constante [PIX\_COLOR](/pt-BR/reference/tools/pix3/functions/pix_color) para usar uma cor predefinida, uma constante [PIX\_COLOR\_INDEX](/pt-BR/reference/tools/pix3/functions/pix_color_index) para usar um índice de cor ou um valor DWORD no formato ARGB para usar uma cor personalizada. Se for especificado um valor DWORD no formato ARGB, o canal alfa desse valor deverá ser definido como `0xff`.

*formatString*   \_In\_\
Tipo: PCWSTR

O nome a ser usado para descrever o evento, como um ponteiro para uma cadeia de caracteres Unicode terminada em nulo. A cadeia de caracteres pode especificar zero ou mais espaços reservados de formato de cadeia de caracteres opcionais, muito semelhantes à formatação de `sprintf`. Este método dá suporte a até 16 espaços reservados.

Tipo: ...

Se espaços reservados forem especificados em *formatString*, você deverá especificar um número correspondente de valores neste parâmetro. Os tipos dos valores especificados neste parâmetro dependem dos tipos identificados pelos espaços reservados correspondentes.

<a id="retvalSection" />

### Valor retornado

Tipo: void

Nenhum.

## Comentários

Esta função cria um evento definido pelo usuário para uma captura de tempo da atividade da CPU, a ser exibido no recurso **Timing Capture** do PIX. Os eventos criados com `PIXScopedEvent` terminam automaticamente quando o escopo em que a API é chamada é encerrado, tornando automática a correspondência entre o início e o fim do evento.

A função `PIXScopedEvent` salva a cadeia de caracteres de formato e os parâmetros de formato em vez de formatar a cadeia de caracteres em tempo de execução. A formatação é feita ao ler os arquivos de captura no PIX. Use cadeias de caracteres alinhadas a 8 bytes ou, de preferência, alinhadas a 16 bytes com `PIXScopedEvent` para obter o melhor desempenho. Para formatar um `char\*` ou `wchar_t\*` como ponteiro usando o especificador de formato `%p`, converta o ponteiro para `void\*` ou para qualquer tipo integral ou de ponto flutuante ao passá-lo para `PIXScopedEvent`.

As chamadas a `PIXScopedEvent` têm garantidos pelo menos 512 bytes de espaço para salvar os dados do registro, o que inclui o tamanho completo e o alinhamento da cadeia de caracteres de formato e de todas as variáveis. Em geral, os eventos do PIX se destinam a marcadores curtos de alto desempenho alinhados aos principais componentes, sistemas ou conteúdos do seu jogo.

Este método normalmente é usado para cronometrar eventos da CPU. No entanto, passar um ponteiro `ID3D12GraphicsCommandList*`, `ID3D12CommandQueue*` ou `ID3D12XboxDmaCommandList*` no parâmetro `context` também permite cronometrar eventos da GPU.

<a id="requirementsSection" />

## Requisitos

**Cabeçalho:** pix3.h

**Biblioteca:** pixevt.lib

**Plataformas compatíveis**: consoles da família XBOX One e consoles XBOX Series

<a id="seealsoSection" />

## Confira também

[PIXScopedEvent](/pt-BR/reference/tools/pix3/functions/pixscopedevent-overloads)\
[PIX3](/pt-BR/reference/tools/pix3/pix3_members)\
[PIX (tópico sob NDA)](/pt-BR/tools/tools-console/pix/pix)


## Related topics

- [Referência de PIXScopedEvent](/pt-BR/reference/tools/pix3/functions/pixscopedevent_2.md)
- [Visão geral de PIXBeginEvent](/pt-BR/reference/tools/pix3/functions/pixbeginevent_4.md)
- [Visão geral da API C de serviços - PFEvents.h](/pt-BR/services/playfab/api-references/c/pfevents/pfevents_members.md)
- [Visão geral da API C de serviços - PFEventPipeline.h](/pt-BR/services/playfab/api-references/c/pfeventpipeline/pfeventpipeline_members.md)
- [Visão geral da API C de serviços - PFEventsTypes.h](/pt-BR/services/playfab/api-references/c/pfeventstypes/pfeventstypes_members.md)