Syntaxe
Paramètres
Type _In_Type : D3D12XBOX_FRAME_EVENT_TYPE Type de l’événement à attendre. TimeOutInMs _In_
Type : UINT Durée, en millisecondes, pendant laquelle attendre que l’événement soit signalé avant de retourner. 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 contenant jusqu’à 63 événements auxiliaires à inclure comme conditions de l’attente. Flags _In_
Type : D3D12XBOX_WAIT_FRAME_EVENT_FLAGS Indicateurs utilisés pour offrir 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 l’image qui a déclenché l’événement.
Valeur de retour
Type : HRESULT Code de réussite ou d’erreur HRESULT. Retourne S_OK si un ou tous les événements spécifiés ont été signalés, satisfaisant ainsi l’attente. Retourne S_FALSE si TimeOutInMs s’est écoulé sans que des événements soient signalés selon la condition d’attente. Retourne 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 image pour satisfaire une attente D3D12XBOX_FRAME_EVENT_ORIGIN. D3DERR_DEVICEREMOVED est également retourné si un autre thread appelle SuspendX pour suspendre l’application pendant la période d’attente. Retourne E_INVALIDARG pour des types d’événements, des listes d’attente et des valeurs d’indicateur non valides, ainsi que si un événement d’image 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, facultativement, un ou tous les événements auxiliaires spécifiés aient été signalés, ou que la durée TimeOutInMs soit écoulée. C’est ainsi que WaitFrameEventX peut être utilisée pour bloquer sur la signalisation des événements d’image ou pour l’interroger.
- Si des événements d’attente auxiliaires sont fournis, l’attente est satisfaite par défaut si l’événement d’image 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 à D3D12XBOX_SIGNALED_OBJECT_INDEX_NONE si l’attente a expiré, à D3D12XBOX_SIGNALED_OBJECT_INDEX_PRIMARY si l’événement d’image lui-même a été signalé, ou sinon à la valeur d’index du premier événement auxiliaire de la liste à avoir été signalé. 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é. Au besoin, 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 image dans le système. Une nouvelle valeur du jeton de pipeline d’image est générée lorsque l’événement d’origine est signalé et qu’une attente sur celui-ci retourne sans expirer. Le pointeur doit être défini à D3D12XBOX_FRAME_PIPELINE_TOKEN_NULL lorsque WaitFrameEventX est appelée avec D3D12XBOX_FRAME_EVENT_ORIGIN, et il contiendra le jeton généré au retour. Ce jeton peut ensuite être utilisé pour associer l’image aux incidents et aux 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’associer les ressources fournies pour l’affichage aux images qui les ont produites. Pour les types d’événements autres que l’origine, l’appelant doit fournir un jeton d’image généré précédemment, afin d’associer l’attente exécutée à l’image 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 sur le processeur de trop devancer l’exécution de la liste sur le GPU et, en fin de compte, l’affichage des images. En général, les origines d’image ne sont signalées (et de nouveaux jetons d’image ne sont produits au retour de l’attente) que si les images précédentes sont terminées et ont atteint l’écran, ou si leurs échéances (établies par SetFrameIntervalX) n’ont pas encore été atteintes. Une exemption est prévue pour permettre à une application de commencer le travail sur une image de manière anticipée, avant que le signal d’origine de l’image n’ait été émis, son jeton de pipeline étant généré et retourné à l’expiration de l’attente. Cela peut être réalisé en incluant l’indicateur D3D12XBOX_WAIT_FRAME_EVENT_FLAG_PROCESS_TOKEN_ON_TIMEOUT, ce qui entraînera probablement une latence de pipeline supplémentaire égale à la différence entre le retour de l’attente et le signal d’origine subséquent (si l’entrée est interrogée après l’attente). Toutefois, même si une image peut être commencée avant que son heure d’origine soit atteinte, elle ne peut pas être traitée pour la présentation. Toute tentative d’utiliser le jeton de pipeline généré prématurément lors d’un appel anticipé à PresentX bloquera la méthode jusqu’à ce que le signal d’origine de l’image ait été émis.