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

> Referência de PIXBeginEvent

# Referência de PIXBeginEvent

Inicia um evento definido pelo usuário para uma captura de tempo da atividade da CPU ou da GPU, a ser exibido nos recursos **System Timing Capture** do PIX.

## Sintaxe

```cpp theme={null}
void PIXBeginEvent(  
         void* context,  
         UINT64 color,  
         PCSTR formatString,
         ...  
)  
```

### Parâmetros

*context*   \
Tipo: void\*

Contexto do evento; aceita `ID3D12GraphicsCommandList\*` , `ID3D12GraphicsCommandList\*` e `ID3D12XboxDmaCommandList\*` (somente XBOX).

*color*   \
Tipo: UINT64

A cor do evento a ser usada no gráfico de tempo do sistema. Use [PIX\_COLOR](/pt-BR/reference/tools/pix3/functions/pix_color) para especificar uma cor, [PIX\_COLOR\_INDEX](/pt-BR/reference/tools/pix3/functions/pix_color_index) para especificar um índice de cor ou passe um DWORD bruto, observando que o formato é ARGB e o valor do canal alfa deve ser 0xff.

*formatString*   \_In\_\
Tipo: PCSTR

O nome a ser usado para descrever o evento, como um ponteiro para uma cadeia de caracteres 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`.

Tipo: ...

Se forem usados espaços reservados em *formatString*, deverá haver um número correspondente de parâmetros cujos tipos dependem dos espaços reservados. Este método dá suporte a no máximo 16 parâmetros de formato.

### Valor retornado

Tipo: void

## Comentários

A função `PIXBeginEvent` 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 em 16 bytes (preferível) ou alinhadas em 8 bytes com PIXBeginEvent para obter o melhor desempenho. Para imprimir um char\* ou wchar\_t\* como ponteiro usando o especificador de formato %p, converta o ponteiro em void\* ou em um ponteiro para um tipo integral ou de ponto flutuante ao passá-lo para `PIXBeginEvent`. Para obter o melhor desempenho, use uma cadeia de caracteres alocada estaticamente.

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

Este método é usado para medir o tempo de eventos da CPU. Para obter mais informações sobre a medição de tempo de eventos da GPU, consulte a seção [APIs de captura de GPU do PIX](/pt-BR/reference/tools/pix3/pix3_members#pixgpucaptureapis) de [PIX3](/pt-BR/reference/tools/pix3/pix3_members).

Cada chamada a `PIXBeginEvent` deve ter uma chamada correspondente a [PIXEndEvent](/pt-BR/reference/tools/pix3/functions/pixendevent). As chamadas emparelhadas a `PIXBeginEvent` e [PIXEndEvent](/pt-BR/reference/tools/pix3/functions/pixendevent) devem ocorrer no mesmo thread.  O intervalo de tempo é de cerca de 200 ns, e a sobrecarga de uso desta função é baixa, portanto, até várias centenas de milhares de chamadas a `PIXBeginEvent` podem ser feitas por segundo.

Os pares `PIXBeginEvent` e `PIXEndEvent` podem ser aninhados em qualquer profundidade.

## Requisitos

**Cabeçalho:** pix3.h

**Biblioteca:** pixevt.lib

**Plataformas com suporte:** consoles da família XBOX One e consoles XBOX Series

## Confira também

[PIXBeginEvent](/pt-BR/reference/tools/pix3/functions/pixbeginevent)\
[PIXBeginEvent\_2](/pt-BR/reference/tools/pix3/functions/pixbeginevent_2)\
[PIXBeginEvent\_4](/pt-BR/reference/tools/pix3/functions/pixbeginevent_4)\
[PIXEndEvent](/pt-BR/reference/tools/pix3/functions/pixendevent)\
[PIX3](/pt-BR/reference/tools/pix3/pix3_members)\
[PIX (tópico sob NDA)](/pt-BR/tools/tools-console/pix/pix)


## Related topics

- [Referencia de PIXBeginEvent](/es/reference/tools/pix3/functions/pixbeginevent_3.md)
- [Referencia de la función PIXBeginEvent](/es/reference/tools/pix3/functions/pixbeginevent_2.md)
- [Referencia de PIXEndEvent](/es/reference/tools/pix3/functions/pixendevent.md)
- [Función PIXBeginEvent](/es/reference/tools/pix3/functions/pixbeginevent.md)
- [Información general de PIXBeginEvent](/es/reference/tools/pix3/functions/pixbeginevent_4.md)