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

# Referência de PIXScopedEvent

> Referência de PIXScopedEvent

# Referência de PIXScopedEvent

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

<a id="syntaxSection" />

## Sintaxe

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

<a id="parametersSection" />

### Parâmetros

*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

<a id="remarksSection" />

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

<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 da função PIXScopedEvent](/pt-BR/reference/tools/pix3/functions/pixscopedevent_3.md)
- [PIXScopedEvent](/pt-BR/reference/tools/pix3/functions/pixscopedevent-overloads.md)
- [Função PIXScopedEvent](/pt-BR/reference/tools/pix3/functions/pixscopedevent.md)
- [Visão geral de PIXScopedEvent](/pt-BR/reference/tools/pix3/functions/pixscopedevent_4.md)
- [Referência de PIXBeginEvent](/pt-BR/reference/tools/pix3/functions/pixbeginevent_3.md)