Sintaxe
Parâmetros
Type _In_Tipo: D3D12XBOX_FRAME_EVENT_TYPE Tipo do evento a ser aguardado. TimeOutInMs _In_
Tipo: UINT Quantidade de tempo, em milissegundos, para aguardar a sinalização do evento antes de retornar. Um valor de D3D12XBOX_WAIT_FRAME_EVENT_INFINITE pode ser usado para aguardar sem possibilidade de tempo limite. pAncillaryWaitList _In_opt_
Tipo: D3D12XBOX_WAIT_FRAME_OBJECT_LIST* Lista opcional de até 63 eventos auxiliares a serem incluídos como condições da espera. Flags _In_
Tipo: D3D12XBOX_WAIT_FRAME_EVENT_FLAGS Sinalizadores usados para fornecer controle adicional sobre a espera. Para obter mais detalhes, consulte Comentários. pToken _Inout_
Tipo: D3D12XBOX_FRAME_PIPELINE_TOKEN* Um identificador do quadro que disparou o evento.
Valor retornado
Tipo: HRESULT Código de êxito ou erro HRESULT. Retorna S_OK se um ou todos os eventos especificados tiverem sido sinalizados, satisfazendo assim a espera. Retorna S_FALSE se TimeOutInMs tiver decorrido sem que os eventos tenham sido sinalizados de acordo com a condição de espera. Retorna D3DERR_DEVICEREMOVED se um tempo limite finito for usado e a GPU travar, impedindo o processamento de um PresentX anterior do qual um novo quadro depende para satisfazer uma espera de D3D12XBOX_FRAME_EVENT_ORIGIN. D3DERR_DEVICEREMOVED também será retornado se outro thread chamar SuspendX para suspender o aplicativo durante o período de espera. Retorna E_INVALIDARG para tipos de evento, listas de espera e valores de sinalizador inválidos, bem como se um evento de quadro do tipo especificado ainda não tiver sido agendado.Comentários
- O método ScheduleFrameEventX deve ser usado para agendar um evento para a espera.
- WaitFrameEventX aguardará até que o evento do tipo especificado ou, opcionalmente, um ou todos os eventos auxiliares especificados tenham sido sinalizados, ou até que a duração de TimeOutInMs tenha passado. É assim que WaitFrameEventX pode ser usado para bloquear na sinalização de eventos de quadro ou para sondá-la.
- Se eventos de espera auxiliares forem fornecidos, a espera será satisfeita, por padrão, se o evento de quadro principal ou qualquer evento auxiliar for sinalizado. No retorno, a memória referenciada pelo membro pSignaledObjectIndex de pAncillaryWaitList será definida como D3D12XBOX_SIGNALED_OBJECT_INDEX_NONE se a espera tiver atingido o tempo limite, D3D12XBOX_SIGNALED_OBJECT_INDEX_PRIMARY se o próprio evento de quadro tiver sido sinalizado ou, caso contrário, o valor de índice do primeiro evento auxiliar da lista a ser sinalizado. Eventos auxiliares de redefinição manual devem ser empregados para determinar se vários eventos foram sinalizados ao satisfazer a espera; nesse caso, no retorno, chamadas a WaitForSingleObject em cada evento auxiliar (com um tempo limite de 0) podem ser feitas para testar o estado sinalizado. Se desejado, a condição de espera do método pode ser alterada para ser satisfeita somente quando todos os objetos tiverem sido sinalizados, incluindo o sinalizador D3D12XBOX_WAIT_FRAME_EVENT_FLAG_WAIT_ALL.
- O D3D12XBOX_FRAME_PIPELINE_TOKEN é usado como um meio de identificar um quadro no sistema. Um novo valor do token de pipeline de quadro será gerado quando o evento de origem for sinalizado e uma espera por ele retornar sem atingir o tempo limite. O ponteiro deve ser definido como D3D12XBOX_FRAME_PIPELINE_TOKEN_NULL quando WaitFrameEventX for chamado com D3D12XBOX_FRAME_EVENT_ORIGIN, e ele conterá o token gerado no retorno. Esse token pode então ser usado para associar o quadro a incidentes e dados relevantes do pipeline, como amostras de entrada, marcadores de renderização e estatísticas. Seu uso é inclusive exigido por PresentX, para identificar os recursos fornecidos para exibição com os quadros que os produziram. Para tipos de evento diferentes de origem, o chamador deve fornecer um token de quadro gerado anteriormente, para associar a espera executada ao quadro que a realiza.
- A espera pelo evento de origem serve como o principal mecanismo de limitação para impedir que a gravação da lista de comandos da CPU avance demais em relação à execução da lista da GPU e, em última instância, à exibição do quadro. Em geral, as origens de quadro serão sinalizadas (e novos tokens de quadro serão produzidos no retorno da espera) somente se os quadros anteriores tiverem sido concluídos e chegado à tela, ou se seus prazos (estabelecidos por SetFrameIntervalX) ainda não tiverem sido atingidos. Uma isenção é fornecida para permitir que um aplicativo comece a trabalhar em um quadro antecipadamente, antes que o sinal de origem do quadro tenha sido emitido, com seu token de pipeline gerado e retornado no tempo limite da espera. Isso pode ser feito incluindo o sinalizador D3D12XBOX_WAIT_FRAME_EVENT_FLAG_PROCESS_TOKEN_ON_TIMEOUT, provavelmente incorrendo em latência adicional de pipeline igual à diferença entre o retorno da espera e o sinal de origem subsequente (caso a entrada seja consultada após a espera). No entanto, embora um quadro possa ser iniciado antes que seu tempo de origem tenha sido atingido, ele não pode ser processado para apresentação. Tentativas de usar o token de pipeline gerado prematuramente com uma chamada antecipada a PresentX farão com que o método seja bloqueado até que o sinal de origem do quadro tenha sido emitido.