Syntaxe
Paramètres
Type _In_Type : D3D12XBOX_FRAME_EVENT_TYPE Type de l’événement à attendre. TimeOutInMs _In_
Type : UINT Durée, en millisecondes, d’attente du signalement de l’événement avant le retour. La valeur D3D12XBOX_WAIT_FRAME_EVENT_INFINITE peut être utilisée pour attendre sans possibilité d’expiration. pAncillaryWaitList _In_opt_
Type : D3D12XBOX_WAIT_FRAME_OBJECT_LIST* Liste facultative de 63 événements auxiliaires au maximum à inclure comme conditions de l’attente. Flags _In_
Type : D3D12XBOX_WAIT_FRAME_EVENT_FLAGS Indicateurs utilisés pour fournir un contrôle supplémentaire sur l’attente. Pour plus de détails, consultez la section Remarques. pToken _Inout_
Type : D3D12XBOX_FRAME_PIPELINE_TOKEN* Identificateur de la trame qui a déclenché l’événement.
Valeur de retour
Type : HRESULT Code de réussite ou d’erreur HRESULT. Renvoie S_OK si un ou tous les événements spécifiés ont été signalés, satisfaisant ainsi l’attente. Renvoie S_FALSE si TimeOutInMs s’est écoulé sans que les événements soient signalés selon la condition d’attente. Renvoie D3DERR_DEVICEREMOVED si un délai d’expiration fini est utilisé et que le GPU se bloque, empêchant le traitement d’un PresentX précédent dont dépend une nouvelle trame pour satisfaire une attente D3D12XBOX_FRAME_EVENT_ORIGIN. D3DERR_DEVICEREMOVED est également renvoyé si un autre thread appelle SuspendX pour suspendre l’application pendant la période d’attente. Renvoie E_INVALIDARG en cas de types d’événements, de listes d’attente ou de valeurs d’indicateur non valides, ainsi que si un événement de trame du type spécifié n’a pas encore été planifié.Remarques
- La méthode ScheduleFrameEventX doit être utilisée pour planifier un événement pour l’attente.
- WaitFrameEventX attend que l’événement du type spécifié ou, éventuellement, un ou tous les événements auxiliaires spécifiés aient été signalés, ou que la durée TimeOutInMs se soit écoulée. C’est ainsi que WaitFrameEventX peut être utilisé pour bloquer sur la signalisation d’un événement de trame ou pour l’interroger.
- Si des événements d’attente auxiliaires sont fournis, l’attente est satisfaite par défaut si l’événement de trame principal ou l’un des événements auxiliaires est signalé. Au retour, la mémoire référencée par le membre pSignaledObjectIndex de pAncillaryWaitList est définie sur D3D12XBOX_SIGNALED_OBJECT_INDEX_NONE si l’attente a expiré, sur D3D12XBOX_SIGNALED_OBJECT_INDEX_PRIMARY si l’événement de trame lui-même a été signalé, ou sinon sur la valeur d’index du premier événement auxiliaire signalé apparaissant dans la liste. Des événements auxiliaires à réinitialisation manuelle doivent être employés pour déterminer si plusieurs événements ont été signalés pour satisfaire l’attente ; au retour, des appels à WaitForSingleObject sur chaque événement auxiliaire (avec un délai d’expiration de 0) peuvent être effectués pour tester l’état signalé. Si vous le souhaitez, la condition d’attente de la méthode peut être modifiée pour n’être satisfaite que lorsque tous les objets ont été signalés, en incluant l’indicateur D3D12XBOX_WAIT_FRAME_EVENT_FLAG_WAIT_ALL.
- Le D3D12XBOX_FRAME_PIPELINE_TOKEN sert à identifier une trame dans le système. Une nouvelle valeur du jeton de pipeline de trame est générée lorsque l’événement d’origine est signalé et qu’une attente sur celui-ci retourne sans expiration. Le pointeur doit être défini sur D3D12XBOX_FRAME_PIPELINE_TOKEN_NULL lorsque WaitFrameEventX est appelé avec D3D12XBOX_FRAME_EVENT_ORIGIN, et il contiendra le jeton généré au retour. Ce jeton peut ensuite être utilisé pour associer la trame aux incidents et données pertinents du pipeline, comme les échantillons d’entrée, les marqueurs de rendu et les statistiques. Son utilisation est même requise par PresentX, afin d’identifier les ressources fournies pour l’affichage avec les trames qui les ont produites. Pour les types d’événements autres que l’origine, l’appelant doit fournir un jeton de trame précédemment généré, afin d’associer l’attente exécutée à la trame qui l’effectue.
- L’attente de l’événement d’origine sert de principal mécanisme de limitation pour empêcher l’enregistrement de la liste de commandes CPU de prendre trop d’avance sur l’exécution de la liste GPU et, en fin de compte, sur l’affichage des trames. En général, les origines de trame ne sont signalées (et de nouveaux jetons de trame ne sont produits au retour de l’attente) que si les trames passées sont terminées et ont atteint l’écran, ou si leurs échéances (établies par SetFrameIntervalX) n’ont pas encore été atteintes. Une exception permet à une application de commencer le travail sur une trame de manière anticipée, avant que le signal d’origine de la trame n’ait été émis, avec son jeton de pipeline généré et renvoyé à l’expiration de l’attente. Cela peut être réalisé en incluant l’indicateur D3D12XBOX_WAIT_FRAME_EVENT_FLAG_PROCESS_TOKEN_ON_TIMEOUT, avec probablement une latence de pipeline supplémentaire égale à la différence entre le retour de l’attente et le signal d’origine suivant (si l’entrée est interrogée après l’attente). Cependant, même si une trame peut être commencée avant que son heure d’origine ne soit atteinte, elle ne peut pas être traitée pour la présentation. Toute tentative d’utilisation du jeton de pipeline généré prématurément avec un appel anticipé à PresentX bloquera la méthode jusqu’à ce que le signal d’origine de la trame ait été émis.