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

# PIXBeginCapture

> PIXBeginCapture

# PIXBeginCapture

Inicia uma captura de tempo do PIX controlada programaticamente.

## Sintaxe

```cpp theme={null}
HRESULT PIXBeginCapture(  
         DWORD captureFlags,  
         const PPIXCaptureParameters captureParameters  
)  
```

### Parâmetros

*captureFlags*   \
Tipo: DWORD

Um sinalizador que indica o tipo de captura a ser realizada. Somente um sinalizador de captura pode ser passado para `PIXBeginCapture` por vez.

*captureParameters*   \_In\_opt\_\
Tipo: PPIXCaptureParameters

Para capturas de tempo, passe um ponteiro para a estrutura `TimingCaptureParameters` ou passe um ponteiro para a união [PIXCaptureParameters](/pt-BR/reference/tools/pix3/structs/pixcaptureparameters), que contém a estrutura `TimingCaptureParameters`.

### Valor retornado

Tipo: HRESULT

Indica se a captura foi iniciada com êxito. S\_FALSE é retornado em caso de êxito. Somente uma captura pode estar em execução por vez. Se `PIXBeginCapture` for chamado enquanto outra captura estiver em execução, E\_PENDING será retornado e a chamada não terá efeito.

#### Sinalizadores

| Sinalizador | Valor | Descrição |
| - | - | - |
| PIX\_CAPTURE\_TIMING | (1 \<\< 0) | Tempo do sistema. |
| PIX\_CAPTURE\_GPU | (1 \<\< 1) | Captura todos os comandos e suas entradas enviados à GPU para que possam ser reproduzidos e analisados. |
| PIX\_CAPTURE\_FUNCTION\_SUMMARY | (1 \<\< 2) | Uma captura de resumo de funções foi iniciada na guia **Home**. |
| PIX\_CAPTURE\_FUNCTION\_DETAILS | (1 \<\< 3) | Uma solicitação de detalhes adicionais de funções foi iniciada usando o botão **Capture Additional Calls** em uma captura de resumo de funções ou de grafo de chamadas. |
| PIX\_CAPTURE\_CALLGRAPH | (1 \<\< 4) | Uma captura de grafo de chamadas foi iniciada pelo PIX ou programaticamente chamando `PIXBeginCapture`. |
| PIX\_CAPTURE\_INSTRUCTION\_TRACE | (1 \<\< 5) | Uma captura de rastreamento de instruções da CPU está em andamento. |
| PIX\_CAPTURE\_SYSTEM\_MONITOR\_COUNTERS | (1 \<\< 6) | Contadores do monitor do sistema. |
| PIX\_CAPTURE\_VIDEO | (1 \<\< 7) | Reprodução de vídeo. |
| PIX\_CAPTURE\_AUDIO | (1 \<\< 8) | Reprodução de áudio. |
| PIX\_CAPTURE\_GPU\_TRACE | (1 \<\< 9) | Captura contadores do SPM (Streaming Performance Monitor) da GPU e dados de SQTT (Shader Queue Thread Tracing) de quase todos os blocos da GPU. |
| PIX\_CAPTURE\_RESERVED | (1 \<\< 15) | Sinalizador de espaço reservado usado internamente pelo PIX para cenários de captura futuros ou especializados. |

<a id="remarksSection" />

## Comentários

Esta função inicia uma captura do PIX a partir do código do título. Atualmente, `PIXBeginCapture` só pode ser usado para fazer uma [captura de tempo (tópico sob NDA)](/pt-BR/tools/tools-console/pix/new-timing-captures).

`PIXBeginCapture` armazena os dados da captura na memória de ferramentas do console.  A quantidade de memória de ferramentas disponibilizada para a captura é especificada definindo o campo `MaximumToolingMemorySizeMb` na estrutura [PIXCaptureParameters](/pt-BR/reference/tools/pix3/structs/pixcaptureparameters).

As capturas de tempo programáticas podem ser feitas em um de dois modos, conforme definido pelo valor da enumeração `PIXCaptureStorage` na estrutura [PIXCaptureParameters](/pt-BR/reference/tools/pix3/structs/pixcaptureparameters).  Quando `PIXCaptureStorage` é definido como *Memory*, `PIXBeginCapture` preencherá a memória de ferramentas disponibilizada e, em seguida, descartará todos os novos dados recebidos.  Quando `PIXCaptureStorage` é definido como *MemoryCircular*, `PIXBeginCapture` usará a memória de ferramentas como um buffer circular.  A captura será executada até que a memória de ferramentas esteja cheia, mas, em vez de interromper a captura, os dados mais antigos serão descartados para abrir espaço para novos dados.  A captura continuará em execução.  As capturas *MemoryCircular* foram projetadas para serem executadas por longos períodos sem esgotar a memória de ferramentas disponível no console.

As capturas de tempo feitas usando `PIXBeginCapture` devem ser copiadas de volta para o PC e convertidas em um arquivo .xpix antes de poderem ser exibidas no PIX.  Confira [Abrindo capturas de tempo programáticas (tópico sob NDA)](/pt-BR/tools/tools-console/pix/open-offline-timing-captures) para obter uma descrição das etapas necessárias para exibir uma captura programática no PIX.

Use [PIXEndCapture](/pt-BR/reference/tools/pix3/functions/pixendcapture) para interromper uma captura do PIX a partir do código do título.

```cpp theme={null}
//
//  timing capture
//
PIXCaptureParameters captureParams = {};

captureParams.TimingCaptureParameters.CaptureGpuTiming = TRUE;
captureParams.TimingCaptureParameters.CaptureCallstacks = TRUE;
captureParams.TimingCaptureParameters.CaptureCpuSamples = TRUE;
captureParams.TimingCaptureParameters.CpuSamplesPerSecond = 4000;

captureParams.TimingCaptureParameters.CaptureStorage = PIXCaptureParameters::Memory;
captureParams.TimingCaptureParameters.FileName = wstrFilename;
captureParams.TimingCaptureParameters.MaximumToolingMemorySizeMb = 4096;

XSF_ERROR_IF_FAILED(PIXBeginCapture(PIX_CAPTURE_TIMING, &captureParams));

```

## Requisitos

**Cabeçalho:** pix3.h

**Biblioteca:** pixevt.lib

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

## Documentação conceitual

* [Análise do desempenho da CPU (conteúdo)](/pt-BR/tools/tools-console/pix/cpu-performance)

## Confira também

[PIXEndCapture](/pt-BR/reference/tools/pix3/functions/pixendcapture)\
[PIXCaptureParameters](/pt-BR/reference/tools/pix3/structs/pixcaptureparameters)\
[PIX3](/pt-BR/reference/tools/pix3/pix3_members)\
[PIX (tópico sob NDA)](/pt-BR/tools/tools-console/pix/pix)


## Related topics

- [PIXBeginCapture](/reference/tools/pix3/functions/pixbegincapture.md)
- [PIXEndCapture](/reference/tools/pix3/functions/pixendcapture.md)
- [PIXCaptureParameters](/reference/tools/pix3/structs/pixcaptureparameters.md)
- [PIXGetCaptureState](/reference/tools/pix3/functions/pixgetcapturestate.md)