Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In diesen Codebeispielen wird die Windows-Implementierungsbibliotheken (WIL) verwendet. Eine bequeme Möglichkeit zum Installieren von WIL besteht darin, zu Visual Studio zu wechseln, auf Project>NuGet-Pakete verwalten...>Durchsuchen, eingeben oder einfügen Microsoft.Windows.ImplementationLibrary im Suchfeld, wählen Sie das Element in den Suchergebnissen aus, und klicken Sie dann auf Installieren, um das Paket für dieses Projekt zu installieren.
Beispiel 1: Erstellen eines Präsentations-Managers auf Systemen, die die Kompositions-Swapchain-API unterstützen
Wie bereits erwähnt, erfordert die Kompositions-Swapchain-API unterstützte Treiber, um zu funktionieren. Das folgende Beispiel veranschaulicht, wie Ihre Anwendung einen Präsentations-Manager erstellen kann, wenn das System die API unterstützt. Dies wird als TryCreate-style-Funktion veranschaulicht, die den Präsentations-Manager nur dann zurückgibt, wenn die API unterstützt wird. Diese Funktion veranschaulicht auch, wie Sie ein Direct3D-Gerät ordnungsgemäß erstellen, um einen Präsentations-Manager zurückzugeben.
C++-Beispiel
bool TryCreatePresentationManager(
_In_ bool requestDirectPresentation,
_Out_ ID3D11Device** ppD3DDevice,
_Outptr_opt_result_maybenull_ IPresentationManager **ppPresentationManager)
{
// Null the presentation manager and Direct3D device initially
*ppD3DDevice = nullptr;
*ppPresentationManager = nullptr;
// Direct3D device creation flags. The composition swapchain API requires that applications disable internal
// driver threading optimizations, as these optimizations are incompatible with the
// composition swapchain API. If this flag is not present, then the API will fail the call to create the
// presentation factory.
UINT deviceCreationFlags =
D3D11_CREATE_DEVICE_BGRA_SUPPORT |
D3D11_CREATE_DEVICE_SINGLETHREADED |
D3D11_CREATE_DEVICE_PREVENT_INTERNAL_THREADING_OPTIMIZATIONS;
// Create the Direct3D device.
com_ptr_failfast<ID3D11DeviceContext> d3dDeviceContext;
FAIL_FAST_IF_FAILED(D3D11CreateDevice(
nullptr, // No adapter
D3D_DRIVER_TYPE_HARDWARE, // Hardware device
nullptr, // No module
deviceCreationFlags, // Device creation flags
nullptr, 0, // Highest available feature level
D3D11_SDK_VERSION, // API version
ppD3DDevice, // Resulting interface pointer
nullptr, // Actual feature level
&d3dDeviceContext)); // Device context
// Call the composition swapchain API export to create the presentation factory.
com_ptr_failfast<IPresentationFactory> presentationFactory;
FAIL_FAST_IF_FAILED(CreatePresentationFactory(
(*ppD3DDevice),
IID_PPV_ARGS(&presentationFactory)));
// Determine whether the system is capable of supporting the composition swapchain API based
// on the capability that's reported by the presentation factory. If your application
// wants direct presentation (that is, presentation without the need for DWM to
// compose, using MPO or iflip), then we query for direct presentation support.
bool isSupportedOnSystem;
if (requestDirectPresentation)
{
isSupportedOnSystem = presentationFactory->IsPresentationSupportedWithIndependentFlip();
}
else
{
isSupportedOnSystem = presentationFactory->IsPresentationSupported();
}
// Create the presentation manager if it is supported on the current system.
if (isSupportedOnSystem)
{
FAIL_FAST_IF_FAILED(presentationFactory->CreatePresentationManager(ppPresentationManager));
}
return isSupportedOnSystem;
}
Beispiel 2 – Erstellen eines Präsentations-Managers und einer Präsentationsoberfläche
Das folgende Beispiel veranschaulicht, wie Ihre Anwendung einen Präsentations-Manager und eine Präsentationsoberfläche erstellt, um eine Bindung an ein visuelles Element in einer visuellen Struktur herzustellen. In nachfolgenden Beispielen wird gezeigt, wie die Präsentationsoberfläche sowohl an DirectComposition- als auch an visuelle Strukturen von Windows.UI.Composition gebunden wird.
C++-Beispiel (DCompositionGetTargetStatistics)
bool MakePresentationManagerAndPresentationSurface(
_Out_ ID3D11Device** ppD3dDevice,
_Out_ IPresentationManager** ppPresentationManager,
_Out_ IPresentationSurface** ppPresentationSurface,
_Out_ unique_handle& compositionSurfaceHandle)
{
// Null the output pointers initially.
*ppD3dDevice = nullptr;
*ppPresentationManager = nullptr;
*ppPresentationSurface = nullptr;
compositionSurfaceHandle.reset();
com_ptr_failfast<IPresentationManager> presentationManager;
com_ptr_failfast<IPresentationSurface> presentationSurface;
com_ptr_failfast<ID3D11Device> d3d11Device;
// Call the function we defined previously to create a Direct3D device and presentation manager, if
// the system supports it.
if (TryCreatePresentationManager(
true, // Request presentation with independent flip.
&d3d11Device,
&presentationManager) == false)
{
// Return 'false' out of the call if the composition swapchain API is unsupported. Assume the caller
// will handle this somehow, such as by falling back to DXGI.
return false;
}
// Use DirectComposition to create a composition surface handle.
FAIL_FAST_IF_FAILED(DCompositionCreateSurfaceHandle(
COMPOSITIONOBJECT_ALL_ACCESS,
nullptr,
compositionSurfaceHandle.addressof()));
// Create presentation surface bound to the composition surface handle.
FAIL_FAST_IF_FAILED(presentationManager->CreatePresentationSurface(
compositionSurfaceHandle.get(),
presentationSurface.addressof()));
// Return the Direct3D device, presentation manager, and presentation surface to the caller for future
// use.
*ppD3dDevice = d3d11Device.detach();
*ppPresentationManager = presentationManager.detach();
*ppPresentationSurface = presentationSurface.detach();
// Return 'true' out of the call if the composition swapchain API is supported and we were able to
// create a presentation manager.
return true;
}
Beispiel 3: Binden einer Präsentationsoberfläche an einen Pinsel "Windows.UI.Composition"
Das folgende Beispiel veranschaulicht, wie Ihre Anwendung einen Kompositionsoberflächenziehpunkt binden würde, der an eine Präsentationsoberfläche gebunden wird, wie im obigen Beispiel erstellt, an eine Windows.UI.Composition- (WinComp) Oberflächenpinsel, die dann an eine sprite-visuelle Darstellung in der visuellen Struktur Ihrer Anwendung gebunden werden kann.
C++-Beispiel
void BindPresentationSurfaceHandleToWinCompTree(
_In_ ICompositor * pCompositor,
_In_ ISpriteVisual * pVisualToBindTo, // The sprite visual we want to bind to.
_In_ unique_handle& compositionSurfaceHandle)
{
// QI an interop compositor from the passed compositor.
com_ptr_failfast<ICompositorInterop> compositorInterop;
FAIL_FAST_IF_FAILED(pCompositor->QueryInterface(IID_PPV_ARGS(&compositorInterop)));
// Create a composition surface for the presentation surface's composition surface handle.
com_ptr_failfast<ICompositionSurface> compositionSurface;
FAIL_FAST_IF_FAILED(compositorInterop->CreateCompositionSurfaceForHandle(
compositionSurfaceHandle.get(),
&compositionSurface));
// Create a composition surface brush, and bind the surface to it.
com_ptr_failfast<ICompositionSurfaceBrush> surfaceBrush;
FAIL_FAST_IF_FAILED(pCompositor->CreateSurfaceBrush(&surfaceBrush));
FAIL_FAST_IF_FAILED(surfaceBrush->put_Surface(compositionSurface.get()));
// Bind the brush to the visual.
auto brush = surfaceBrush.query<ICompositionBrush>();
FAIL_FAST_IF_FAILED(pVisualToBindTo->put_Brush(brush.get()));
}
Beispiel 4– Binden einer Präsentationsoberfläche an eine visuelle DirectComposition-Visualisierung
Im folgenden Beispiel wird veranschaulicht, wie Ihre Anwendung eine Präsentationsoberfläche an eine Visuelle DirectComposition (DComp-) in einer visuellen Struktur binden würde.
C++-Beispiel
void BindPresentationSurfaceHandleToDCompTree(
_In_ IDCompositionDevice* pDCompDevice,
_In_ IDCompositionVisual* pVisualToBindTo,
_In_ unique_handle& compositionSurfaceHandle) // The composition surface handle that was
// passed to CreatePresentationSurface.
{
// Create a DComp surface to wrap the presentation surface.
com_ptr_failfast<IUnknown> dcompSurface;
FAIL_FAST_IF_FAILED(pDCompDevice->CreateSurfaceFromHandle(
compositionSurfaceHandle.get(),
&dcompSurface));
// Bind the presentation surface to the visual.
FAIL_FAST_IF_FAILED(pVisualToBindTo->SetContent(dcompSurface.get()));
}
Beispiel 5: Festlegen des Alphamodus und des Farbraums auf einer Präsentationsoberfläche
Im folgenden Beispiel wird veranschaulicht, wie Ihre Anwendung den Alphamodus und den Farbraum auf einer Präsentationsoberfläche festlegen würde. Der Alphamodus beschreibt, ob und wie der Alphakanal in der Textur interpretiert werden soll. Der Farbraum beschreibt den Farbraum, auf den die Texturpixel verweisen.
Alle Eigenschaftsupdates wie diese werden als Teil der nächsten Gegenwart der Anwendung wirksam und werden atomar zusammen mit allen Pufferupdates wirksam, die Teil dieser Anwendung sind. Ein Vorhandener kann auch, wenn Ihre Anwendung wünscht, keine Puffer überhaupt aktualisieren und stattdessen nur aus Eigenschaftsupdates bestehen. Alle Präsentationsoberflächen, deren Puffer auf einem bestimmten Present nicht aktualisiert werden, bleiben an den Puffer gebunden, an den sie vor dieser Präsentation gebunden waren.
C++-Beispiel
void SetAlphaModeAndColorSpace(
_In_ IPresentationSurface* pPresentationSurface)
{
// Set alpha mode.
FAIL_FAST_IF_FAILED(pPresentationSurface->SetAlphaMode(DXGI_ALPHA_MODE_IGNORE));
// Set color space to full RGB.
FAIL_FAST_IF_FAILED(pPresentationSurface->SetColorSpace(DXGI_COLOR_SPACE_RGB_FULL_G22_NONE_P709));
}
Beispiel 6: Festlegen von Letterboxing-Rändern auf einer Präsentationsoberfläche
Das folgende Beispiel veranschaulicht, wie Ihre Anwendung Letterboxing-Ränder auf einer Präsentationsoberfläche angeben würde. Letterboxing wird verwendet, um einen angegebenen Bereich außerhalb des Oberflächeninhalts selbst auszufüllen, um unterschiedliche Seitenverhältnisse zwischen Inhalt und Anzeigegerät zu berücksichtigen, auf dem es angezeigt wird. Ein gutes Beispiel hierfür sind die schwarzen Balken, die oft über und unter inhalten sichtbar sind, wenn sie auf einem PC einen Film sehen, der für Breitbildtheater formatiert ist. Mit der Kompositions-Swapchain-API können Sie die Ränder angeben, in denen letterboxing in solchen Fällen gerendert werden soll.
Derzeit werden Briefboxbereiche immer mit undurchsichtigem Schwarz gefüllt.
Als visueller Strukturinhalt ist die Präsentationsoberfläche im Koordinatenbereich des visuellen Hostbereichs vorhanden. Bei vorhandener Letterboxing entspricht der Ursprung des Koordinatenbereichs des visuellen Elements der oberen linken Ecke des Letterboxings. Das heißt, der Puffer selbst ist im Koordinatenbereich des visuellen Elements versetzt. Die Grenzen werden als Größe des Puffers und die Größe des Letterboxings berechnet.
Im Folgenden wird veranschaulicht, wo der Puffer und das Letterboxing im visuellen Koordinatenbereich vorhanden sind und wie Grenzen berechnet werden.
Wenn die transformation, die auf eine Präsentationsoberfläche angewendet wird, mit einem Offset versehen ist, wird der Bereich, der nicht vom Puffer oder dem Letterboxing abgedeckt wird, außerhalb der Grenzen des Inhalts betrachtet und als transparent behandelt – ähnlich wie alle anderen visuellen Strukturinhalte außerhalb der Inhaltsgrenzen behandelt werden.
Letterboxing- und Transformationsinteraktion
Um konsistente Letterboxing-Randgrößen unabhängig von der Skalierung bereitzustellen, die Ihre Anwendung auf einen Puffer anwendet, um einen Inhaltsbereich auszufüllen, versucht DWM, die Ränder unabhängig von der Skalierung in einer konsistenten Größe zu rendern, wobei jedoch das Ergebnis der Transformation berücksichtigt wird, die auf die Präsentationsoberfläche angewendet wurde.
Auf eine andere Weise werden Letterboxing-Ränder technisch angewendet, bevor die Transformation der Präsentationsoberfläche angewendet wird, aber alle Skalierungen ausgleichen, die Teil dieser Transformation sein könnten. Das heißt, die Transformation der Präsentationsoberfläche wird in zwei Komponenten dekonstruiert – der Teil der Transformation, die skaliert wird, und den Rest der Transformation.
Bei 100px Letterboxing-Seitenrändern und ohne Transformation auf die Präsentationsoberfläche wird der resultierende Puffer ohne Skalierung gerendert, und die Letterbox-Seitenränder sind 100 Pixel breit.
Ein weiteres Beispiel, bei 100px Letterboxing-Seitenrändern und einer 2x-Skalierungstransformation, die auf die Präsentationsoberfläche angewendet wird, wird der resultierende Puffer mit einer Skalierung von 2x gerendert, und die Auf dem Bildschirm angezeigten Letterbox-Seitenränder sind immer noch 100px in allen Größen.
Ein weiteres Beispiel, bei einer 45-Grad-Drehungstransformation werden die resultierenden Letterboxing-Seitenränder 100px angezeigt, und die Letterbox-Seitenränder werden mit dem Puffer gedreht.
Ein weiteres Beispiel: Bei einer Transformation von 2x und Drehung von 45 Grad wird das Bild gedreht und skaliert, und die Letterbox-Seitenränder sind ebenfalls 100px breit und werden mit dem Puffer gedreht.
Wenn eine Skalierungstransformation nicht eindeutig aus der Transformation extrahiert werden kann, die Ihre Anwendung auf die Präsentationsoberfläche anwendet, z. B. wenn die resultierende X- oder Y-Skalierung 0 ist, werden die Letterboxing-Ränder mit der gesamten angewendeten Transformation gerendert, und wir versuchen nicht, die Skalierung auszugleichen.
C++-Beispiel
void SetContentLayoutAndFill(
_In_ IPresentationSurface* pPresentationSurface)
{
// Set layout properties. Each layout property is described below.
// The source RECT describes the area from the bound buffer that will be sampled from. The
// RECT is in source texture coordinates. Below we indicate that we'll sample from a
// 100x100 area on the source texture.
RECT sourceRect;
sourceRect.left = 0;
sourceRect.top = 0;
sourceRect.right = 100;
sourceRect.bottom = 100;
FAIL_FAST_IF_FAILED(pPresentationSurface->SetSourceRect(&sourceRect));
// The presentation transform defines how the source rect will be transformed when
// rendering the buffer. In this case, we indicate we want to scale it 2x in both
// width and height, and we also want to offset it 50 pixels to the right.
PresentationTransform transform = { 0 };
transform.M11 = 2.0f; // X scale 2x
transform.M22 = 2.0f; // Y scale 2x
transform.M31 = 50.0f; // X offset 50px
FAIL_FAST_IF_FAILED(pPresentationSurface->SetTransform(&transform));
// The letterboxing parameters describe how to letterbox the content. Letterboxing
// is commonly used to fill area not covered by video/surface content when scaling to
// an aspect ratio that doesn't match the aspect ratio of the surface itself. For
// example, when viewing content formatted for the theater on a 1080p home screen, one
// can typically see black "bars" on the top and bottom of the video, covering the space
// on screen that wasn't covered by the video due to the differing aspect ratios of the
// content and the display device. The composition swapchain API allows the user to specify
// letterboxing margins, which describe the number of pixels to surround the surface
// content with on screen. In this case, surround the top and bottom of our content with
// 100 pixel tall letterboxing.
FAIL_FAST_IF_FAILED(pPresentationSurface->SetLetterboxingMargins(
0.0f,
100.0f,
0.0f,
100.0f));
}
Beispiel 7– Festlegen von Inhaltsbeschränkungen auf einer Präsentationsoberfläche
Das folgende Beispiel veranschaulicht, wie Ihre Anwendung verhindern würde, dass andere Anwendungen den Inhalt der Präsentationsoberfläche (aus Technologien wie PrintScreen, DDA, Capture API und anderen) für geschützte Inhalte lesen. Außerdem wird veranschaulicht, wie die Anzeige einer Präsentationsoberfläche auf eine einzige DXGI-Ausgabe beschränkt wird.
Wenn das Zurücklesen von Inhalten deaktiviert ist, enthält das aufgenommene Bild anstelle der Präsentationsoberfläche undurchsichtig schwarz, wenn die Anwendung versucht, zurückzulesen. Wenn eine Präsentationsoberfläche auf eine IDXGIOutput-beschränkt ist, wird sie in allen anderen Ausgaben als undurchsichtig schwarz angezeigt.
C++-Beispiel
void SetContentRestrictions(
_In_ IPresentationSurface* pPresentationSurface,
_In_ IDXGIOutput* pOutputToRestrictTo)
{
// Disable readback of the surface via printscreen, bitblt, etc.
FAIL_FAST_IF_FAILED(pPresentationSurface->SetDisableReadback(true));
// Restrict display of surface to only the passed output.
FAIL_FAST_IF_FAILED(pPresentationSurface->RestrictToOutput(pOutputToRestrictTo));
}
Beispiel 8: Hinzufügen von Präsentationspuffern zu einem Präsentations-Manager
Im folgenden Beispiel wird veranschaulicht, wie Ihre Anwendung eine Reihe von Direct3D-Texturen zuweist, und fügen Sie sie dem Präsentations-Manager hinzu, um sie als Präsentationspuffer zu verwenden, die präsentationsoberflächen präsentiert werden können.
Wie bereits erwähnt, gibt es keine Einschränkungen hinsichtlich der Anzahl der Präsentationsmanager, bei denen eine Textur registriert werden kann. In den meisten normalen Anwendungsfällen wird eine Textur jedoch nur für einen einzelnen Präsentations-Manager registriert.
Beachten Sie außerdem, dass da die API freigegebene Pufferhandles als Währung akzeptiert, wenn Texturen als Präsentationspuffer im Präsentations-Manager registriert werden, und da DXGI mehrere freigegebene Puffer für eine einzelne Texture2D erstellen kann, ist es technisch möglich, dass Ihre Anwendung mehrere freigegebene Pufferhandles für eine einzelne Textur erstellt und beide beim Präsentations-Manager registriert wird. im Wesentlichen mit dem Effekt, denselben Puffer mehrmals hinzuzufügen. Dies wird nicht empfohlen, da die vom Präsentations-Manager bereitgestellten Synchronisierungsmechanismen aufgehoben werden, da zwei präsentationspuffer, die eindeutig nachverfolgt werden, tatsächlich derselben Textur entsprechen. Da es sich hierbei um eine erweiterte API handelt, und da es bei der Implementierung tatsächlich ziemlich schwierig ist, diesen Fall zu erkennen, versucht die API nicht, dieses Szenario zu überprüfen.
C++-Beispiel
void AddBuffersToPresentationManager(
_In_ ID3D11Device* pD3D11Device, // The backing Direct3D device
_In_ IPresentationManager* pPresentationManager, // Previously-made presentation manager
_In_ UINT bufferWidth, // The width of the buffers to add
_In_ UINT bufferHeight, // The height of the buffers to add
_In_ UINT numberOfBuffersToAdd, // The number of buffers to add to the presentation manager
_Out_ vector<com_ptr_failfast<ID3D11Texture2D>>& textures, // Array of textures returned
_Out_ vector<com_ptr_failfast<IPresentationBuffer>>& presentationBuffers) // Array of presentation buffers returned
{
// Clear the returned vectors initially.
textures.clear();
presentationBuffers.clear();
// Add the desired buffers to the presentation manager.
for (UINT i = 0; i < numberOfBuffersToAdd; i++)
{
com_ptr_failfast<ID3D11Texture2D> texture;
com_ptr_failfast<IPresentationBuffer> presentationBuffer;
// Call our helper to make a new buffer of the desired type.
AddNewPresentationBuffer(
pD3D11Device,
pPresentationManager,
bufferWidth,
bufferHeight,
&texture,
&presentationBuffer);
// Track our buffers in our own set of vectors.
textures.push_back(texture);
presentationBuffers.push_back(presentationBuffer);
}
}
void AddNewPresentationBuffer(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager,
_In_ UINT bufferWidth,
_In_ UINT bufferHeight,
_Out_ ID3D11Texture2D** ppTexture2D,
_Out_ IPresentationBuffer** ppPresentationBuffer)
{
com_ptr_failfast<ID3D11Texture2D> texture2D;
unique_handle sharedResourceHandle;
// Create a shared Direct3D texture and handle with the passed attributes.
MakeD3D11Texture(
pD3D11Device,
bufferWidth,
bufferHeight,
&texture2D,
out_param(sharedResourceHandle));
// Add the texture2D to the presentation manager, and get back a presentation buffer.
com_ptr_failfast<IPresentationBuffer> presentationBuffer;
FAIL_FAST_IF_FAILED(pPresentationManager->AddBufferFromSharedHandle(
sharedResourceHandle.get(),
&presentationBuffer));
// Return back the texture and buffer presentation buffer.
*ppTexture2D = texture2D.detach();
*ppPresentationBuffer = presentationBuffer.detach();
}
void MakeD3D11Texture(
_In_ ID3D11Device* pD3D11Device,
_In_ UINT textureWidth,
_In_ UINT textureHeight,
_Out_ ID3D11Texture2D** ppTexture2D,
_Out_ HANDLE* sharedResourceHandle)
{
D3D11_TEXTURE2D_DESC textureDesc = {};
// Width and height can be anything within max texture size of the adapter backing the Direct3D
// device.
textureDesc.Width = textureWidth;
textureDesc.Height = textureHeight;
// MipLevels and ArraySize must be 1.
textureDesc.MipLevels = 1;
textureDesc.ArraySize = 1;
// Format can be one of the following:
// DXGI_FORMAT_B8G8R8A8_UNORM
// DXGI_FORMAT_R8G8B8A8_UNORM
// DXGI_FORMAT_R16G16B16A16_FLOAT
// DXGI_FORMAT_R10G10B10A2_UNORM
// DXGI_FORMAT_NV12
// DXGI_FORMAT_YUY2
// DXGI_FORMAT_420_OPAQUE
// For this
textureDesc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
// SampleDesc count and quality must be 1 and 0 respectively.
textureDesc.SampleDesc.Count = 1;
textureDesc.SampleDesc.Quality = 0;
// Usage must be D3D11_USAGE_DEFAULT.
textureDesc.Usage = D3D11_USAGE_DEFAULT;
// BindFlags must include D3D11_BIND_SHADER_RESOURCE for RGB textures, and D3D11_BIND_DECODER
// for YUV textures. For RGB textures, it is likely your application will want to specify
// D3D11_BIND_RENDER_TARGET in order to render to it.
textureDesc.BindFlags =
D3D11_BIND_SHADER_RESOURCE |
D3D11_BIND_RENDER_TARGET;
// MiscFlags should include D3D11_RESOURCE_MISC_SHARED and D3D11_RESOURCE_MISC_SHARED_NTHANDLE,
// and might also include D3D11_RESOURCE_MISC_SHARED_DISPLAYABLE if your application wishes to
// qualify for MPO and iflip. If D3D11_RESOURCE_MISC_SHARED_DISPLAYABLE is not provided, then the
// content will not qualify for MPO or iflip, but can still be composed by DWM
textureDesc.MiscFlags =
D3D11_RESOURCE_MISC_SHARED |
D3D11_RESOURCE_MISC_SHARED_NTHANDLE |
D3D11_RESOURCE_MISC_SHARED_DISPLAYABLE;
// CPUAccessFlags must be 0.
textureDesc.CPUAccessFlags = 0;
// Use Direct3D to create a texture 2D matching the desired attributes.
com_ptr_failfast<ID3D11Texture2D> texture2D;
FAIL_FAST_IF_FAILED(pD3D11Device->CreateTexture2D(&textureDesc, nullptr, &texture2D));
// Create a shared handle for the texture2D.
unique_handle sharedBufferHandle;
auto dxgiResource = texture2D.query<IDXGIResource1>();
FAIL_FAST_IF_FAILED(dxgiResource->CreateSharedHandle(
nullptr,
GENERIC_ALL,
nullptr,
&sharedBufferHandle));
// Return the handle to the caller.
*ppTexture2D = texture2D.detach();
*sharedResourceHandle = sharedBufferHandle.release();
}
Beispiel 9 – Entfernen von Präsentationspuffern aus einem Präsentations-Manager und Objektlebensdauer
Das Entfernen eines Präsentationspuffers aus dem Präsentations-Manager ist so einfach wie das Freigeben des IPresentationBuffer-Objekts in eine 0-Referenzanzahl. In diesem Fall bedeutet dies jedoch nicht unbedingt, dass der Präsentationspuffer freigegeben werden kann. Es kann Fälle geben, in denen ein Puffer weiterhin verwendet wird, z. B. wenn dieser Präsentationspuffer auf dem Bildschirm sichtbar ist oder ausstehende Präsentationen enthält, auf die verwiesen wird.
Kurz gesagt, der Präsentations-Manager verfolgt, wie jeder Puffer von Ihrer Anwendung direkt und indirekt verwendet wird. Sie verfolgt, welche Puffer angezeigt werden, welche Darstellungen ausstehend sind, und Referenzpuffer werden intern nachverfolgt, um sicherzustellen, dass ein Puffer nicht wirklich freigegeben/aufgehoben wird, bis er wirklich nicht mehr verwendet wird.
Eine gute Möglichkeit, sich über die Pufferlebensdauer gedanken zu machen, besteht darin, dass die API nicht mehr in zukünftigen Aufrufen verwendet wird, wenn Ihre Anwendung einen IPresentationBuffer veröffentlicht. Die Kompositions-Swapchain-API verfolgt dies sowie alle anderen Verwendungsmöglichkeiten des Puffers und gibt den Puffer nur dann vollständig frei, wenn er völlig sicher ist.
Kurz gesagt: Ihre Anwendung sollte eine IPresentationBuffer- freigeben, wenn sie damit fertig ist, und wissen, dass die Kompositions-Swapchain-API den Puffer vollständig freigeben wird, wenn alle anderen Verwendungen ebenfalls abgeschlossen sind.
Hier ist eine Abbildung der oben genannten Konzepte.
In diesem Beispiel haben wir einen Präsentations-Manager mit zwei Präsentationspuffern. Puffer 1 enthält drei Verweise, die sie lebendig halten.
- Ihre Anwendung enthält eine IPresentationBuffer- darauf verweisen.
- Intern für die API wird sie als aktueller gebundener Puffer der Präsentationsoberfläche gespeichert, da es sich um den letzten Puffer handelte, den Die Anwendung gebunden hat, die sie dann präsentiert hat.
- Es gibt auch eine Präsentation, die in der aktuellen Warteschlange vorhanden ist, die Puffer 1 auf der Präsentationsoberfläche anzeigen soll.
Puffer 1 hält zusätzlich einen Verweis auf die entsprechende Direct3D-Texturzuweisung. Ihre Anwendung verfügt außerdem über eine ID3D11Texture2D-, die auf diese Zuordnung verweist.
Puffer 2 verfügt nicht mehr über ausstehende Verweise von der Anwendungsseite, noch wird die Texturzuordnung, auf die er verweist, aber Puffer 2 wird lebendig gehalten, da es sich um das handelt, was derzeit auf der Präsentationsoberfläche auf dem Bildschirm angezeigt wird. Wenn "Present 1" verarbeitet wird und stattdessen puffer 1 auf dem Bildschirm angezeigt wird, enthält Puffer 2 keine weiteren Verweise, und er wird freigegeben, sodass der Verweis auf seine Direct3D-Textur2D-Zuordnung freigegeben wird.
C++-Beispiel
void ReleasePresentationManagerBuffersExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager)
{
com_ptr_failfast<ID3D11Texture2D> texture2D;
com_ptr_failfast<IPresentationBuffer> newBuffer;
// Create a new texture/presentation buffer.
AddNewPresentationBuffer(
pD3D11Device,
pPresentationManager,
200, // Buffer width
200, // Buffer height
&texture2D,
&newBuffer);
// Release the IPresentationBuffer. This indicates that we have no more intention to use it
// from the application side. However, if we have any presents outstanding that reference
// the buffer, it will be kept alive internally and released when all outstanding presents
// have been retired.
newBuffer.reset();
// When the presentation buffer is truly released internally, it will in turn release its
// reference on the texture2D which it corresponds to. Your application must also release
// its own references to the texture2D for it to be released.
texture2D.reset();
}
Beispiel 10 – Ändern der Größe von Puffern in einem Präsentations-Manager
Das folgende Beispiel veranschaulicht, wie Ihre Anwendung eine Größe der Präsentationspuffer ändern würde. Wenn z. B. ein Filmstreamingdienst 480p streamingt, sich jedoch aufgrund der Verfügbarkeit hoher Netzwerkbandbreite auf 1080p entscheidet, würde er seine Puffer von 480p auf 1080p umstellen, sodass es mit der Darstellung von 1080p-Inhalten beginnen könnte.
In DXGI wird dies als Größenänderung Vorgangs bezeichnet. DXGI gliedert alle Puffer atomisch neu, was kostspielig ist, und kann ein Schlitz auf dem Bildschirm erzeugen. Im folgenden Beispiel wird beschrieben, wie Sie die Größe von Atomen auf Parität mit DXGI in der Kompositions-Swapchain-API erzielen. In einem späteren Beispiel wird gezeigt, wie Sie eine Größenänderung in einer gestaffelten Mode durchführen, wobei der Abstand zwischen der Neuverteilung über mehrere Präsentationen verteilt wird und eine bessere Leistung erzielt wird als eine atomische Swapchain-Größenänderung.
C++-Beispiel
void ResizePresentationManagerBuffersExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager) // Previously-made presentation manager.
{
// Vectors representing the IPresentationBuffer and ID3D11Texture2D collections.
vector<com_ptr_failfast<ID3D11Texture2D>> textures;
vector<com_ptr_failfast<IPresentationBuffer>> presentationBuffers;
// Add 6 50x50 buffers to the presentation manager. See previous example for definition of
// this function.
AddBuffersToPresentationManager(
pD3D11Device,
pPresentationManager,
50, // Buffer width
50, // Buffer height
6, // Number of buffers
textures,
presentationBuffers);
// Release all the buffers we just added. The presentation buffers internally will be released
// when any other references are also removed (outstanding presents, display references, etc.).
textures.clear();
presentationBuffers.clear();
// Add 6 new 100x100 buffers to the presentation manager to replace the
// old ones we just removed.
AddBuffersToPresentationManager(
pD3D11Device,
pPresentationManager,
100, // Buffer width
100, // Buffer height
6, // Number of buffers
textures,
presentationBuffers);
}
Beispiel 11: Synchronisieren der Präsentation mithilfe von puffer verfügbaren Ereignissen und Behandeln verlorener Ereignisse des Präsentations-Managers
Wenn Ihre Anwendung eine Präsentation mit einem Präsentationspuffer ausstellen wird, der in einer früheren Präsentation verwendet wurde, müssen Sie sicherstellen, dass die vorherige Präsentation abgeschlossen ist, um den Präsentationspuffer erneut zu rendern und darzustellen. Die Kompositions-Swapchain-API bietet einige verschiedene Mechanismen, um diese Synchronisierung zu vereinfachen. Am einfachsten ist das verfügbaren Ereigniseines Präsentationspuffers, bei dem es sich um ein NT-Ereignisobjekt handelt, das signalisiert wird, wenn ein Puffer verwendet werden kann (d. h. alle vorherigen Präsentationen haben entweder die eingestellt oder eingestellt Zustand) eingegeben und andernfalls nicht signalisiert. In diesem Beispiel wird veranschaulicht, wie Puffer verfügbare Ereignisse zum Auswählen verfügbarer Puffer verwendet werden. Außerdem wird veranschaulicht, wie sie auf Gerät hören, die Fehler verloren gegangen sind, die moralisch dem DXGI-Geräteverlust entsprechen und eine Wiederherstellung des Präsentationsmanagers erfordern.
Fehler beim Präsentations-Manager verloren
Ein Präsentationsmanager kann verloren gehen, wenn intern ein Fehler auftritt, von dem er nicht wiederhergestellt werden kann. Ihre Anwendung muss einen verloren gegangenen Präsentationsmanager zerstören und stattdessen einen neuen erstellen. Wenn ein Präsentationsmanager verloren geht, nimmt er keine weiteren Präsentationen mehr an. Jeder Versuch, Present für einen verlorenen Präsentations-Manager aufzurufen, wird PRESENTATION_ERROR_LOSTzurückgegeben. Alle anderen Methoden funktionieren jedoch normal. Dies besteht darin, sicherzustellen, dass Ihre Anwendung nur nach PRESENTATION_ERROR_LOST bei vorhandenen Aufrufen suchen muss und dass verlorene Fehler bei jedem API-Aufruf nicht vorhergesehen/behandelt werden müssen. Wenn Ihre Anwendung nach fehlern außerhalb eines aktuellen Aufrufs suchen oder darüber benachrichtigt werden möchte, kann sie das verlorene Ereignis verwenden, das von IPresentationManager::GetLostEventzurückgegeben wird.
Warteschlange und Anzeigedauer präsentieren
Präsentationen, die vom Präsentations-Manager ausgegeben werden, können einen bestimmten Zeitpunkt für das Ziel angeben. Diese Zielzeit ist die ideale Zeit, zu der das System versucht, die Gegenwart anzuzeigen. Da Bildschirme zu einem begrenzten Zeitplan aktualisiert werden, wird die Gegenwart wahrscheinlich nicht genau zu dem angegebenen Zeitpunkt angezeigt, aber es wird so nah wie möglich angezeigt.
Bei dieser Zielzeit handelt es sich um eine systemrelative Zeit oder die Zeit, die das System seit dem Einschalten in Hunderten von Nanosekunden ausgeführt hat. Eine einfache Möglichkeit zum Berechnen der aktuellen Zeit ist das Abfragen aktueller QueryPerformanceCounter (QPC)-Werts, dividieren sie durch die QPC-Häufigkeit des Systems und multiplizieren sie mit 10.000.000. Abgesehen von Rundungs- und Genauigkeitsgrenzwerten berechnet dies die aktuelle Zeit in anwendbaren Einheiten. Das System kann auch die aktuelle Zeit abrufen, indem MfGetSystemTimeoder QueryInterruptTimePreciseaufgerufen wird.
Sobald die aktuelle Uhrzeit bekannt ist, gibt Ihre Anwendung in der Regel zu steigenden Offsets von der aktuellen Zeit aus.
Unabhängig von der Zielzeit werden die Präsentieren immer in der Warteschlangenreihenfolge verarbeitet. Auch wenn ein aktuelles Ziel eine frühere Zeit als die vorherige Gegenwart ist, wird sie erst verarbeitet, nachdem die vorherige Präsentation verarbeitet wurde. Dies bedeutet im Wesentlichen, dass alle Vorhandenen, die nicht auf einen späteren Zeitpunkt abzielen, als dies vorher überschreibt. Dies bedeutet auch, dass, wenn Ihre Anwendung eine aktuelle so früh wie möglichausgeben möchte, kann sie einfach keine Zielzeit festlegen (in diesem Fall bleibt die Zielzeit für das letzte Mal vorhanden), oder legen Sie eine Zielzeit von 0 fest. Beide hätten dieselbe Wirkung. Wenn Ihre Anwendung nicht warten möchte, bis vorherige Präsentationen abgeschlossen sind, bis eine neue Präsentation stattfindet, muss sie vorherige Präsentationen abbrechen. Ein zukünftiges Beispiel beschreibt, wie dies zu tun ist.
T=3s: Präsentieren 1, 2, 3 bereit und 3, als letzte Gegenwart, gewinnt aus. T=4s: Präsentieren Sie 4, 5, 6 bereit und 6, als letzte Gegenwart, gewinnt aus.
Das obige Diagramm veranschaulicht ein Beispiel für herausragende Präsentationen in der aktuellen Warteschlange. 1 zielt auf eine Zeit von 3s ab. So findet bis 3s keine Geschenke statt. Gegenwärtig sind jedoch 2 ziele tatsächlich eine frühere Zeit, 2s und stellen auch 3 Ziele 3s dar. Als solche werden 3s zur Zeit 1, 2 und 3 vollständig sein, und 3 wird die Gegenwart sein, die tatsächlich wirksam wird. Danach wird die nächste Gegenwart, 4, mit 4s zufrieden sein, aber sofort von Present 5 außer Kraft gesetzt, die auf 0s und Present 6 ausgerichtet ist, die keine Zielzeit festgelegt hat. Sowohl 5 als auch 6 wirksam wirken so früh wie möglich.
C++-Beispiel
bool SimpleEventSynchronizationExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager,
_In_ IPresentationSurface* pPresentationSurface,
_In_ vector<com_ptr_failfast<ID3D11Texture2D>>& textures,
_In_ vector<com_ptr_failfast<IPresentationBuffer>>& presentationBuffers)
{
// Track a time we'll be presenting to below. Default to the current time, then increment by
// 1/10th of a second every present.
SystemInterruptTime presentTime;
QueryInterruptTimePrecise(&presentTime.value);
// Build an array of events that we can wait on to perform various actions in our work loop.
vector<unique_event> waitEvents;
// The lost event will be the first event in our list. This is an event that signifies that
// something went wrong in the system (due to extreme conditions such as memory pressure, or
// driver issues) that indicate that the presentation manager has been lost, and should no
// longer be used, and instead should be recreated.
unique_event lostEvent;
pPresentationManager->GetLostEvent(&lostEvent);
waitEvents.emplace_back(std::move(lostEvent));
// Add each buffer's available event to the list of events we will be waiting on.
for (UINT bufferIndex = 0; bufferIndex < presentationBuffers.size(); bufferIndex++)
{
unique_event availableEvent;
presentationBuffers[bufferIndex]->GetAvailableEvent(&availableEvent);
waitEvents.emplace_back(std::move(availableEvent));
}
// Iterate for 120 presents.
constexpr UINT numberOfPresents = 120;
for (UINT onPresent = 0; onPresent < numberOfPresents; onPresent++)
{
// Advance our present time 1/10th of a second in the future. Note the API accepts
// time in 100ns units, or 1/1e7 of a second, meaning that 1 million units correspond to
// 1/10th of a second.
presentTime.value += 1'000'000;
// Wait for the lost event or an available buffer. Since WaitForMultipleObjects prioritizes
// lower-indexed events, it is recommended to put any higher importance events (like the
// lost event) first, and then follow up with buffer available events.
DWORD waitResult = WaitForMultipleObjects(
static_cast<UINT>(waitEvents.size()),
reinterpret_cast<HANDLE*>(waitEvents.data()),
FALSE,
INFINITE);
// Failfast if the wait hit an error.
FAIL_FAST_IF((waitResult - WAIT_OBJECT_0) >= waitEvents.size());
// Our lost event was the first event in the array. If this is signaled, the caller
// should recreate the presentation manager. This is very similar to how Direct3D devices
// can be lost. Assume our caller knows to handle this return value appropriately.
if (waitResult == WAIT_OBJECT_0)
{
return false;
}
// Otherwise, compute the buffer corresponding to the available event that was signaled.
UINT bufferIndex = waitResult - (WAIT_OBJECT_0 + 1);
// Draw red to that buffer
DrawColorToSurface(
pD3D11Device,
textures[bufferIndex],
1.0f, // red
0.0f, // green
0.0f); // blue
// Bind the presentation buffer to the presentation surface. Changes in this binding will take
// effect on the next present, and the binding persists across presents. That is, any number
// of subsequent presents will imply this binding until it is changed. It is completely fine
// to only update buffers for a subset of the presentation surfaces owned by a presentation
// manager on a given present - the implication is that it simply didn't update.
//
// Similarly, note that if your application were to call SetBuffer on the same presentation
// surface multiple times without calling present, this is fine. The policy is last writer
// wins.
//
// Your application may present without first binding a presentation surface to a buffer.
// The result will be that presentation surface will simply have no content on screen,
// similar to how DComp and WinComp surfaces appear in a tree before they are rendered to.
// In that case system content will show through where the buffer would have been.
//
// Your application may also set a 'null' buffer binding after previously having bound a
// buffer and present - the end result is the same as if your application had presented
// without ever having set the content.
pPresentationSurface->SetBuffer(presentationBuffers[bufferIndex].get());
// Present at the targeted time. Note that a present can target only a single time. If an
// application wants to updates two buffers at two different times, then it must present
// two times.
//
// Presents are always processed in queue order. A present will not take effect before any
// previous present in the queue, even if it targets an earlier time. In such a case, when
// the previous present is processed, the next present will also be processed immediately,
// and override that previous present.
//
// For this reason, if your application wishes to present "now" or "early as possible", then
// it can simply present, without setting a target time. The implied target time will be 0,
// and the new present will override the previous present.
//
// If your application wants to present truly "now", and not wait for previous presents in the
// queue to be processed, then it will need to cancel previous presents. A future example
// demonstrates how to do this.
//
// Your application will receive PRESENTATION_ERROR_LOST if it attempts to Present a lost
// presentation manager. This is the only call that will return such an error. A lost
// presentation manager functions normally in every other case, so applications need only
// to handle this error at the time they call Present.
pPresentationManager->SetTargetTime(presentTime);
HRESULT hrPresent = pPresentationManager->Present();
if (hrPresent == PRESENTATION_ERROR_LOST)
{
// Our presentation manager has been lost. Return 'false' to the caller to indicate that
// the presentation manager should be recreated.
return false;
}
else
{
FAIL_FAST_IF_FAILED(hrPresent);
}
}
return true;
}
void DrawColorToSurface(
_In_ ID3D11Device* pD3D11Device,
_In_ const com_ptr_failfast<ID3D11Texture2D>& texture2D,
_In_ float redValue,
_In_ float greenValue,
_In_ float blueValue)
{
com_ptr_failfast<ID3D11DeviceContext> D3DDeviceContext;
com_ptr_failfast<ID3D11RenderTargetView> renderTargetView;
// Get the immediate context from the D3D11 device.
pD3D11Device->GetImmediateContext(&D3DDeviceContext);
// Create a render target view of the passed texture.
auto resource = texture2D.query<ID3D11Resource>();
FAIL_FAST_IF_FAILED(pD3D11Device->CreateRenderTargetView(
resource.get(),
nullptr,
renderTargetView.addressof()));
// Clear the texture with the specified color.
float clearColor[4] = { redValue, greenValue, blueValue, 1.0f }; // red, green, blue, alpha
D3DDeviceContext->ClearRenderTargetView(renderTargetView.get(), clearColor);
}
Beispiel 12 – Erweiterte Synchronisierung – Einschränkung des Workflows auf die Größe der ausstehenden Warteschlange mit vorhandenen Synchronisierungszäunen und Behandeln verlorener Ereignisse des Präsentations-Managers
Im folgenden Beispiel wird veranschaulicht, wie Ihre Anwendung eine große Anzahl von Geschenken für die Zukunft übermitteln kann, und dann in den Ruhezustand einschlafen, bis die Anzahl der noch ausstehenden Darstellungen auf eine bestimmte Menge fällt. Frameworks wie Windows Media Foundation drosseln auf diese Weise, um die Anzahl der auftretenden CPU-Wakes zu minimieren, während gleichzeitig sichergestellt wird, dass die aktuelle Warteschlange nicht erschöpft ist (was eine reibungslose Wiedergabe verhindert und zu einem Glitch führt). Dies wirkt sich auf die Minimierung des CPU-Stromverbrauchs während des Präsentationsworkflows aus. Ihre Anwendung stellt die maximale Anzahl von Präsentationen in die Warteschlange (basierend auf der Anzahl der präsentationspuffer, die sie zugewiesen haben) in die Warteschlange ein, und schlafen Sie dann bis direkt vor dem Schließen der aktuellen Warteschlange, um die Warteschlange erneut zu füllen.
C++-Beispiel
bool FenceSynchronizationExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager,
_In_ IPresentationSurface* pPresentationSurface,
_In_ vector<com_ptr_failfast<ID3D11Texture2D>>& textures,
_In_ vector<com_ptr_failfast<IPresentationBuffer>>& presentationBuffers)
{
// Track a time we'll be presenting to below. Default to the current time, then increment by
// 1/10th of a second every present.
SystemInterruptTime presentTime;
QueryInterruptTimePrecise(&presentTime.value);
// Get present retiring fence.
com_ptr_failfast<ID3D11Fence> presentRetiringFence;
FAIL_FAST_IF_FAILED(pPresentationManager->GetPresentRetiringFence(
IID_PPV_ARGS(&presentRetiringFence)));
// Get the lost event to query before presentation.
unique_event lostEvent;
pPresentationManager->GetLostEvent(&lostEvent);
// Create an event to synchronize to our queue depth with. We'll use Direct3D to signal this event
// when our synchronization fence indicates reaching a specific present.
unique_event presentQueueSyncEvent;
presentQueueSyncEvent.create(EventOptions::ManualReset);
// Cycle the present queue 10 times.
constexpr UINT numberOfPresentRefillCycles = 10;
for (UINT onRefillCycle = 0; onRefillCycle < numberOfPresentRefillCycles; onRefillCycle++)
{
// Fill up presents for all presentation buffers. We compare the presentation manager's
// next present ID to the present confirmed fence's value to figure out how
// far ahead we are. We stop when we've issued presents for all buffers.
while ((pPresentationManager->GetNextPresentId() -
presentRetiringFence->GetCompletedValue()) < presentationBuffers.size())
{
// Present buffers in cyclical pattern. We can figure out the current buffer to
// present by taking the modulo of the next present ID by the number of buffers. Note that the
// first present of a presentation manager always has a present ID of 1 and increments by 1 on
// each subsequent present. A present ID of 0 is conceptually meant to indicate that "no
// presents have taken place yet".
UINT bufferIndex = static_cast<UINT>(
pPresentationManager->GetNextPresentId() % presentationBuffers.size());
// Assert that the passed buffer is tracked as available for presentation. Because we throttle
// based on the total number of buffers, this should always be true.
NT_ASSERT(presentationBuffers[bufferIndex]->IsAvailable());
// Advance our present time 1/10th of a second in the future.
presentTime.value += 1'000'000;
// Draw red to the texture.
DrawColorToSurface(
pD3D11Device,
textures[bufferIndex],
1.0f, // red
0.0f, // green
0.0f); // blue
// Bind the presentation buffer to the presentation surface.
pPresentationSurface->SetBuffer(presentationBuffers[bufferIndex].get());
// Present at the targeted time.
pPresentationManager->SetTargetTime(presentTime);
HRESULT hrPresent = pPresentationManager->Present();
if (hrPresent == PRESENTATION_ERROR_LOST)
{
// Our presentation manager has been lost. Return 'false' to the caller to indicate that
// the presentation manager should be recreated.
return false;
}
else
{
FAIL_FAST_IF_FAILED(hrPresent);
}
};
// Now that the buffer is full, go to sleep until the present queue has been drained to
// the desired queue depth. To figure out the appropriate present to wake on, we subtract
// the desired wake queue depth from the presentation manager's last present ID. We
// use Direct3D's SetEventOnCompletion to signal our wait event when that particular present
// is retiring, and then wait on that event. Note that the semantic of SetEventOnCompletion
// is such that even if we happen to call it after the fence has already reached the
// requested value, the event will be set immediately.
constexpr UINT wakeOnQueueDepth = 2;
presentQueueSyncEvent.ResetEvent();
FAIL_FAST_IF_FAILED(presentRetiringFence->SetEventOnCompletion(
pPresentationManager->GetNextPresentId() - 1 - wakeOnQueueDepth,
presentQueueSyncEvent.get()));
HANDLE waitHandles[] = { lostEvent.get(), presentQueueSyncEvent.get() };
DWORD waitResult = WaitForMultipleObjects(
ARRAYSIZE(waitHandles),
waitHandles,
FALSE,
INFINITE);
// Failfast if we hit an error during our wait.
FAIL_FAST_IF((waitResult - WAIT_OBJECT_0) >= ARRAYSIZE(waitHandles));
if (waitResult == WAIT_OBJECT_0)
{
// The lost event was signaled - return 'false' to the caller to indicate that
// the presentation manager was lost.
return false;
}
// Iterate into another refill cycle.
}
return true;
}
Beispiel 13– VSync-Unterbrechungen und Hardware-Flip-Warteschlangenunterstützung
Eine neue Form der Flip-Warteschlangenverwaltung namens Hardware Flip Queue wurde zusammen mit dieser API eingeführt, wodurch GPU-Hardware im Wesentlichen vollständig unabhängig von der CPU verwaltet werden kann. Der Hauptvorteil ist die Energieeffizienz. Wenn die CPU nicht an dem Präsentationsprozess beteiligt sein muss, wird weniger Leistung gezeichnet.
Der Nachteil, dass der GPU-Handle unabhängig dargestellt wird, besteht darin, dass der CPU-Zustand nicht mehr sofort widergespiegelt werden kann, wenn Darstellungen angezeigt werden. Kompositions-Swapchain-API-Konzepte wie Puffer verfügbare Ereignisse, Synchronisierungszäune und vorhandene Statistiken werden nicht sofort aktualisiert. Stattdessen aktualisiert die GPU nur in regelmäßigen Abständen den CPU-Zustand, was angezeigt wurde. Dies bedeutet, dass Das Feedback an Anwendungen bezüglich des aktuellen Status mit einer Latenz zusammenkommt.
Ihre Anwendung kümmert sich in der Regel darum, wenn einige Geschenke angezeigt werden, aber nicht so viel zu anderen Geschenken interessiert sind. Wenn Ihre Anwendung z. B. 10 ausgibt, kann sie entscheiden, dass sie wissen möchte, wann der 8. angezeigt wird, damit sie mit dem erneuten Ausfüllen der aktuellen Warteschlange beginnen kann. In diesem Fall ist das einzige Geschenk, von dem es wirklich Feedback möchte, ist der 8. Es ist nicht geplant, etwas zu tun, wenn 1-7 oder 9 angezeigt werden.
Gibt an, ob der Aktualisierungs-CPU-Zustand angezeigt wird, hängt davon ab, ob die GPU-Hardware so konfiguriert ist, dass ein VSync-Interrupt generiert wird, wenn diese angezeigt wird. Dieser VSync-Interrupt weckt die CPU, wenn sie noch nicht aktiv ist, und die CPU führt dann speziellen Code auf Kernelebene aus, um sich auf die Präsentationen zu aktualisieren, die seit der letzten Überprüfung auf der GPU aufgetreten sind, und aktualisiert wiederum Feedbackmechanismen wie Puffer verfügbare Ereignisse, den gegenwärtigen Abbruchzaun und präsentieren Statistiken.
Damit Ihre Anwendung explizit angeben kann, welche Präsentationen einen VSync-Interrupt ausgeben sollen, macht der Präsentations-Manager eine IPresentationManager::ForceVSyncInterrupt-Methode verfügbar, die angibt, ob nachfolgende Präsentationen einen VSync-Interrupt ausgeben sollen. Diese Einstellung gilt für alle zukünftigen Darstellungen, bis sie geändert wird, ähnlich wie IPresentationManager::SetTargetTime und IPresentationManager::SetPreferredPresentDuration.
Wenn diese Einstellung auf einer bestimmten Gegenwart aktiviert ist, benachrichtigt die Hardware die CPU sofort, wenn diese angezeigt wird, wobei mehr Energie verwendet wird, aber sichergestellt wird, dass die CPU sofort benachrichtigt wird, wenn eine Präsentation stattfindet, damit Anwendungen so schnell wie möglich reagieren können. Wenn diese Einstellung für eine bestimmte Gegenwart deaktiviert ist, kann das System die CPU beim Anzeigen der CPU zurückstellen – stromsparend, aber das Feedback zurückstellen.
Ihre Anwendung erzwingt in der Regel keinen VSync-Interrupt für alle Präsentationen, es sei denn, sie möchte mit einer Präsentation synchronisiert werden. Da Ihre Anwendung im obigen Beispiel nach dem Erneuten Ausfüllen der aktuellen Warteschlange angezeigt wurde, würde sie anfordern, dass 8 Signale einen VSync-Interrupt signalisieren, aber 1-7 und 9 präsentieren nicht.
Wenn Ihre Anwendung diese Einstellung nicht konfiguriert, signalisiert der Präsentations-Manager standardmäßig immer den VSync-Interrupt, wenn jede Präsentation angezeigt wird. Anwendungen, die sich nicht über die Energienutzung oder nicht über die Unterstützung der Hardware flip-Warteschlange kümmern, können einfach nicht ForceVSyncInterruptaufrufen, und sie werden daher garantiert synchronisiert. Anwendungen, die sich der Hardware-Flip-Warteschlangenunterstützung bewusst sind, können diese Einstellung explizit für eine verbesserte Energieeffizienz steuern.
Es folgt ein Diagramm, das das Verhalten der API in Bezug auf VSync-Unterbrechungseinstellungen beschreibt.
C++-Beispiel
bool ForceVSyncInterruptPresentsExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager,
_In_ IPresentationSurface* pPresentationSurface,
_In_ vector<com_ptr_failfast<ID3D11Texture2D>>& textures,
_In_ vector<com_ptr_failfast<IPresentationBuffer>>& presentationBuffers)
{
// Track a time we'll be presenting to below. Default to the current time, then increment by
// 1/10th of a second every present.
SystemInterruptTime presentTime;
QueryInterruptTimePrecise(&presentTime.value);
// Get present retiring fence.
com_ptr_failfast<ID3D11Fence> presentRetiringFence;
FAIL_FAST_IF_FAILED(pPresentationManager->GetPresentRetiringFence(
IID_PPV_ARGS(&presentRetiringFence)));
// Get the lost event to query before presentation.
unique_event lostEvent;
pPresentationManager->GetLostEvent(&lostEvent);
// Create an event to synchronize to our queue depth with. We will use Direct3D to signal this event
// when our synchronization fence indicates reaching a specific present.
unique_event presentQueueSyncEvent;
presentQueueSyncEvent.create(EventOptions::ManualReset);
// Issue 10 presents, and wake when the present queue is 2 entries deep (which happens when
// present 7 is retiring).
constexpr UINT wakeOnQueueDepth = 2;
constexpr UINT numberOfPresents = 10;
const UINT presentIdToWakeOn = numberOfPresents - 1 - wakeOnQueueDepth;
while (pPresentationManager->GetNextPresentId() <= numberOfPresents)
{
UINT bufferIndex = static_cast<UINT>(
pPresentationManager->GetNextPresentId() % presentationBuffers.size());
// Advance our present time 1/10th of a second in the future.
presentTime.value += 1'000'000;
// Draw red to the texture.
DrawColorToSurface(
pD3D11Device,
textures[bufferIndex],
1.0f, // red
0.0f, // green
0.0f); // blue
// Bind the presentation buffer to the presentation surface.
pPresentationSurface->SetBuffer(presentationBuffers[bufferIndex].get());
// Present at the targeted time.
pPresentationManager->SetTargetTime(presentTime);
// If this present is not going to retire the present that we want to wake on when it is shown, then
// we don't need immediate updates to buffer available events, present retiring fence, or present
// statistics. As such, we can mark it as not requiring a VSync interrupt, to allow for greater
// power efficiency on machines with hardware flip queue support.
bool forceVSyncInterrupt = (pPresentationManager->GetNextPresentId() == (presentIdToWakeOn + 1));
pPresentationManager->ForceVSyncInterrupt(forceVSyncInterrupt);
HRESULT hrPresent = pPresentationManager->Present();
if (hrPresent == PRESENTATION_ERROR_LOST)
{
// Our presentation manager has been lost. Return 'false' to the caller to indicate that
// the presentation manager should be recreated.
return false;
}
else
{
FAIL_FAST_IF_FAILED(hrPresent);
}
}
// Now that the buffer is full, go to sleep until presentIdToWakeOn has begun retiring. We
// configured the subsequent present to force a VSync interrupt when it is shown, which will ensure
// this wait is completed immediately.
presentQueueSyncEvent.ResetEvent();
FAIL_FAST_IF_FAILED(presentRetiringFence->SetEventOnCompletion(
presentIdToWakeOn,
presentQueueSyncEvent.get()));
HANDLE waitHandles[] = { lostEvent.get(), presentQueueSyncEvent.get() };
DWORD waitResult = WaitForMultipleObjects(
ARRAYSIZE(waitHandles),
waitHandles,
FALSE,
INFINITE);
// Failfast if we hit an error during our wait.
FAIL_FAST_IF((waitResult - WAIT_OBJECT_0) >= ARRAYSIZE(waitHandles));
if (waitResult == WAIT_OBJECT_0)
{
// The lost event was signaled - return 'false' to the caller to indicate that
// the presentation manager was lost.
return false;
}
return true;
}
Beispiel 14– Das Abbrechen von Terminen wird für die Zukunft geplant
Medienanwendungen, die in der Warteschlange für die Zukunft präsentiert werden, können sich entscheiden, die zuvor ausgestellten Präsentieren abzubrechen. Dies kann beispielsweise passieren, wenn Ihre Anwendung ein Video wiederzugeben, eine große Anzahl von Frames für die Zukunft ausgegeben hat, und der Benutzer entscheidet, die Videowiedergabe anzuhalten. In diesem Fall möchte Ihre Anwendung den aktuellen Frame beibehalten und zukünftige Frames abbrechen, die noch nicht in die Warteschlange gestellt wurden. Dies kann auch passieren, wenn eine Medienanwendung entscheidet, die Wiedergabe an einen anderen Punkt im Video zu verschieben. In diesem Fall möchte Ihre Anwendung alle Präsentieren abbrechen, die noch nicht in die Warteschlange für die alte Position im Video eingereiht wurden, und sie durch Die Präsentierten für die neue Position ersetzen. In diesem Fall kann Ihre Anwendung nach dem Abbrechen vorheriger Vorzeichen neue Präsentierten in der Zukunft ausstellen, die dem neuen Punkt im Video entsprechen.
C++-Beispiel
void PresentCancelExample(
_In_ IPresentationManager* pPresentationManager,
_In_ UINT64 firstPresentIDToCancelFrom)
{
// Assume we've issued a number of presents in the future. Something happened in the app, and
// we want to cancel the issued presents that occur after a specified time or present ID. This
// may happen, for example, when the user pauses playback from inside a media application. The
// application will want to cancel all presents posted targeting beyond the pause time. The
// cancel will apply to all previously posted presents whose present IDs are at least
// 'firstPresentIDToCancelFrom'. Note that Present IDs are always unique, and never recycled,
// so even if a present is canceled, no subsequent present will ever reuse its present ID.
//
// Also note that if some presents we attempt to cancel can't be canceled because they've
// already started queueing, then no error will be returned, they simply won't be canceled as
// requested. Cancelation takes a "best effort" approach.
FAIL_FAST_IF_FAILED(pPresentationManager->CancelPresentsFrom(firstPresentIDToCancelFrom));
// In the case where the media application scrubbed to a different position in the video, it may now
// choose to issue new presents to replace the ones canceled. This is not illustrated here, but
// previous examples that demonstrate presentation show how this may be achieved.
}
Beispiel 15 – Gestaffelter Pufferänderungsvorgang für eine verbesserte Leistung
In diesem Beispiel wird veranschaulicht, wie ihre Anwendung die Größe von Pufferänderungen für eine verbesserte Leistung über DXGI ändern kann. Erinnern Sie sich an unser vorheriges Beispiel zur Größenänderung, wobei ein Filmstreamingdienstclient die Wiedergabeauflösung von 720p auf 1080p ändern möchte. In DXGI führt die Anwendung einen Größenänderungsvorgang für den DXGI-Swapchain durch, der alle vorherigen Puffer atomisch wegwirft und alle neuen 1080p-Puffer gleichzeitig neu zuordnen und der Swapchain hinzufügen würde. Diese Art der atomigen Größenänderung von Puffern ist teuer und hat das Potenzial, eine lange Zeit in Anspruch zu nehmen und Störungen zu verursachen. Die neue API bietet eine bessere Kontrolle über einzelne Präsentationspuffer. Als solche können Puffer neu zugeordnet und 1:1 über mehrere Dargestellte ersetzt werden, um die Arbeitsauslastung im Laufe der Zeit aufzuteilen. Dies hat weniger Auswirkungen auf ein vorhandenes Element und ist viel weniger wahrscheinlich, dass es zu Störungen kommt. Im Wesentlichen kann Ihre Anwendung für einen Präsentations-Manager mit n-Präsentationspuffern einen alten Präsentationspuffer in der alten Größe entfernen, einen neuen Präsentationspuffer in der neuen Größe zuweisen und präsentieren. Nachdem 'n' angezeigt wird, befinden sich alle Puffer in der neuen Größe.
C++-Beispiel
bool StaggeredResizeExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager,
_In_ IPresentationSurface* pPresentationSurface,
_In_ vector<com_ptr_failfast<ID3D11Texture2D>> textures,
_In_ vector<com_ptr_failfast<IPresentationBuffer>> presentationBuffers)
{
// Track a time we'll be presenting to below. Default to the current time, then increment by
// 1/10th of a second every present.
SystemInterruptTime presentTime;
QueryInterruptTimePrecise(&presentTime.value);
// Assume textures/presentationBuffers vector contains 10 100x100 buffers, and we want to resize
// our swapchain to 200x200. Instead of reallocating 10 200x200 buffers all at once,
// like DXGI does today, we can stagger the reallocation across multiple presents. For
// each present, we can allocate one buffer at the new size, and replace one old buffer
// at the old size with the new one at the new size. After 10 presents, we will have
// reallocated all our buffers, and we will have done so in a manner that's much less
// likely to produce delays or glitches.
constexpr UINT numberOfBuffers = 10;
for (UINT bufferIndex = 0; bufferIndex < numberOfBuffers; bufferIndex++)
{
// Advance our present time 1/10th of a second in the future.
presentTime.value += 1'000'000;
// Release the old texture/presentation buffer at the presented index.
auto& replacedTexture = textures[bufferIndex];
auto& replacedPresentationBuffer = presentationBuffers[bufferIndex];
replacedTexture.reset();
replacedPresentationBuffer.reset();
// Create a new texture/presentation buffer in its place.
AddNewPresentationBuffer(
pD3D11Device,
pPresentationManager,
200, // Buffer width
200, // Buffer height
&replacedTexture,
&replacedPresentationBuffer);
// Draw red to the new texture.
DrawColorToSurface(
pD3D11Device,
replacedTexture,
1.0f, // red
0.0f, // green
0.0f); // blue
// Bind the presentation buffer to the presentation surface.
pPresentationSurface->SetBuffer(replacedPresentationBuffer.get());
// Present at the targeted time.
pPresentationManager->SetTargetTime(presentTime);
HRESULT hrPresent = pPresentationManager->Present();
if (hrPresent == PRESENTATION_ERROR_LOST)
{
// Our presentation manager has been lost. Return 'false' to the caller to indicate that
// the presentation manager should be recreated.
return false;
}
else
{
FAIL_FAST_IF_FAILED(hrPresent);
}
}
return true;
}
Beispiel 16 – Lesen und Verarbeiten vorhandener Statistiken
Die API-Berichte stellen Statistiken für jede übermittelte Präsentation dar. Auf hoher Ebene sind aktuelle Statistiken ein Feedbackmechanismus, der beschreibt, wie eine bestimmte Gegenwart verarbeitet oder vom System dargestellt wurde. Es gibt verschiedene Arten von Statistiken, die Ihre Anwendung für den Empfang registrieren kann, und die Statistikinfrastruktur in der API selbst soll erweiterbar sein, sodass in Zukunft weitere Arten von Statistiken hinzugefügt werden können. Diese API beschreibt, wie Sie Statistiken lesen und die Typen von Statistiken beschreiben, die heute definiert wurden, und welche Informationen sie auf hoher Ebene vermitteln.
C++-Beispiel
// This is an identifier we'll assign to our presentation surface that will be used to reference that
// presentation surface in statistics. This is to avoid referring to a presentation surface by pointer
// in a statistics structure, which has unclear refcounting and lifetime semantics.
static constexpr UINT_PTR myPresentedContentTag = 12345;
bool StatisticsExample(
_In_ ID3D11Device* pD3D11Device,
_In_ IPresentationManager* pPresentationManager,
_In_ IPresentationSurface* pPresentationSurface,
_In_ vector<com_ptr_failfast<ID3D11Texture2D>>& textures,
_In_ vector<com_ptr_failfast<IPresentationBuffer>>& presentationBuffers)
{
// Track a time we'll be presenting to below. Default to the current time, then increment by
// 1/10th of a second every present.
SystemInterruptTime presentTime;
QueryInterruptTimePrecise(&presentTime.value);
// Register to receive 3 types of statistics.
FAIL_FAST_IF_FAILED(pPresentationManager->EnablePresentStatisticsKind(
PresentStatisticsKind_CompositionFrame,
true));
FAIL_FAST_IF_FAILED(pPresentationManager->EnablePresentStatisticsKind(
PresentStatisticsKind_PresentStatus,
true));
FAIL_FAST_IF_FAILED(pPresentationManager->EnablePresentStatisticsKind(
PresentStatisticsKind_IndependentFlipFrame,
true));
// Stats come back referencing specific presentation surfaces. We assign 'tags' to presentation
// surfaces in the API that statistics will use to reference the presentation surface in a
// statistic.
pPresentationSurface->SetTag(myPresentedContentTag);
// Build an array of events that we can wait on.
vector<unique_event> waitEvents;
// The lost event will be the first event in our list. This is an event that signifies that
// something went wrong in the system (due to extreme conditions like memory pressure, or
// driver issues) that indicate that the presentation manager has been lost, and should no
// longer be used, and instead should be recreated.
unique_event lostEvent;
FAIL_FAST_IF_FAILED(pPresentationManager->GetLostEvent(&lostEvent));
waitEvents.emplace_back(std::move(lostEvent));
// The statistics event will be the second event in our list. This event will be signaled
// by the presentation manager when there are statistics to read back.
unique_event statisticsEvent;
FAIL_FAST_IF_FAILED(pPresentationManager->GetPresentStatisticsAvailableEvent(&statisticsEvent));
waitEvents.emplace_back(std::move(statisticsEvent));
// Add each buffer's available event to the list of events we will be waiting on.
for (UINT bufferIndex = 0; bufferIndex < presentationBuffers.size(); bufferIndex++)
{
unique_event availableEvent;
presentationBuffers[bufferIndex]->GetAvailableEvent(&availableEvent);
waitEvents.emplace_back(std::move(availableEvent));
}
// Iterate our workflow 120 times.
constexpr UINT iterationCount = 120;
for (UINT i = 0; i < iterationCount; i++)
{
// Wait for an event to be signaled.
DWORD waitResult = WaitForMultipleObjects(
static_cast<UINT>(waitEvents.size()),
reinterpret_cast<HANDLE*>(waitEvents.data()),
FALSE,
INFINITE);
// Failfast if the wait hit an error.
FAIL_FAST_IF((waitResult - WAIT_OBJECT_0) >= waitEvents.size());
// Our lost event was the first event in the array. If this is signaled, then the caller
// should recreate the presentation manager. This is very similar to how Direct3D devices
// can be lost. Assume our caller knows to handle this return value appropriately.
if (waitResult == WAIT_OBJECT_0)
{
return false;
}
// The second event in the array is the statistics event. If this event is signaled,
// read and process our statistics.
if (waitResult == (WAIT_OBJECT_0 + 1))
{
StatisticsExample_ProcessStatistics(pPresentationManager);
}
// Otherwise, the event corresponds to a buffer available event that is signaled.
// Compute the buffer for the available event that was signaled and present a
// frame.
else
{
DWORD bufferIndex = waitResult - (WAIT_OBJECT_0 + 2);
// Draw red to the texture.
DrawColorToSurface(
pD3D11Device,
textures[bufferIndex],
1.0f, // red
0.0f, // green
0.0f); // blue
// Bind the texture to the presentation surface.
pPresentationSurface->SetBuffer(presentationBuffers[bufferIndex].get());
// Advance our present time 1/10th of a second in the future.
presentTime.value += 1'000'000;
// Present at the targeted time.
pPresentationManager->SetTargetTime(presentTime);
HRESULT hrPresent = pPresentationManager->Present();
if (hrPresent == PRESENTATION_ERROR_LOST)
{
// Our presentation manager has been lost. Return 'false' to the caller to indicate that
// the presentation manager should be recreated.
return false;
}
else
{
FAIL_FAST_IF_FAILED(hrPresent);
}
}
}
return true;
}
void StatisticsExample_ProcessStatistics(
_In_ IPresentationManager* pPresentationManager)
{
// Dequeue a single present statistics item. This will return the item
// and pop it off the queue of statistics.
com_ptr_failfast<IPresentStatistics> presentStatisticsItem;
pPresentationManager->GetNextPresentStatistics(&presentStatisticsItem);
// Read back the present ID this corresponds to.
UINT64 presentId = presentStatisticsItem->GetPresentId();
UNREFERENCED_PARAMETER(presentId);
// Switch on the type of statistic this item corresponds to.
switch (presentStatisticsItem->GetKind())
{
case PresentStatisticsKind_PresentStatus:
{
// Present status statistics describe whether a given present was queued for display,
// skipped due to some future present being a better candidate to display on a given
// frame, or canceled via the API.
auto presentStatusStatistics = presentStatisticsItem.query<IPresentStatusStatistics>();
// Read back the status
PresentStatus status = presentStatusStatistics->GetPresentStatus();
UNREFERENCED_PARAMETER(status);
// Possible values for status:
// PresentStatus_Queued
// PresentStatus_Skipped
// PresentStatus_Canceled;
// Depending on the status returned, your application can adjust their workflow
// accordingly. For example, if your application sees that a large percentage of their
// presents are skipped, it means they are presenting more frames than the system can
// display. In such a case, your application might decided to lower the rate at which
// you present frames.
}
break;
case PresentStatisticsKind_CompositionFrame:
{
// Composition frame statistics describe how a given present was used in a DWM frame.
// It includes information such as which monitors displayed the present, whether the
// present was composed or directly scanned out via an MPO plane, and rendering
// properties such as what transforms were applied to the rendering. Composition
// frame statistics are not issued for iflip presents - only for presents issued by the
// compositor. iflip presents have their own type of statistic (described next).
auto compositionFrameStatistics =
presentStatisticsItem.query<ICompositionFramePresentStatistics>();
// Stats should come back for the present statistics item that we tagged earlier.
NT_ASSERT(compositionFrameStatistics->GetContentTag() == myPresentedContentTag);
// The composition frame ID indicates the DWM frame ID that the present was used
// in.
CompositionFrameId frameId = compositionFrameStatistics->GetCompositionFrameId();
// Get the display instance array to indicate which displays showed the present. Each
// instance of the presentation surface will have an entry in this array. For example,
// if your application adds the same presentation surface to four different visuals in the
// visual tree, then each instance in the tree will have an entry in the display instance
// array. Similarly, if the presentation surface shows up on multiple monitors, then each
// monitor instance will be accounted for in the display instance array that is
// returned.
//
// Note that the pointer returned from GetDisplayInstanceArray is valid for the
// lifetime of the ICompositionFramePresentStatistics. Your application must not attempt
// to read this pointer after the ICompositionFramePresentStatistics has been released
// to a refcount of 0.
UINT displayInstanceArrayCount;
const CompositionFrameDisplayInstance* pDisplayInstances;
compositionFrameStatistics->GetDisplayInstanceArray(
&displayInstanceArrayCount,
&pDisplayInstances);
for (UINT i = 0; i < displayInstanceArrayCount; i++)
{
const auto& displayInstance = pDisplayInstances[i];
// The following are fields that are available in a display instance.
// The LUID, VidPnSource, and unique ID of the output and its owning
// adapter. The unique ID will be bumped when a LUID/VidPnSource is
// recycled. Applications should use the unique ID to determine when
// this happens so that they don't try and correlate stats from one
// monitor with another.
displayInstance.outputAdapterLUID;
displayInstance.outputVidPnSourceId;
displayInstance.outputUniqueId;
// The instanceKind field indicates how the present was used. It
// indicates that the present was composed (rendered to DWM's backbuffer),
// scanned out (via MPO/DFlip) or composed to an intermediate buffer by DWM
// for effects.
displayInstance.instanceKind;
// The finalTransform field indicates the transform at which the present was
// shown in world space. It will include all ancestor visual transforms and
// can be used to know how it was rendered in the global visual tree.
displayInstance.finalTransform;
// The requiredCrossAdapterCopy field indicates whether or not we needed to
// copy your application's buffer to a different adapter in order to display
// it. Applications should use this to determine whether or not they should
// reallocate their buffers onto a different adapter for better performance.
displayInstance.requiredCrossAdapterCopy;
// The colorSpace field indicates the colorSpace of the output that the
// present was rendered to.
displayInstance.colorSpace;
// For example, if your application sees that the finalTransform is scaling your
// content by 2x, you might elect to pre-render that scale into your presentation
// surface, and then add a 1/2 scale. At which point, the finalTransform should
// be 1x, and some MPO hardware will be more likely to MPO a presentation surface
// with a 1x scale applied, since some hardware has a maximum they are able to
// scale in an MPO plane. Similarly, if your application's content is being scaled
// down on screen, you may wish to simply render its content at a
// smaller scale to conserve resources, and apply an enlargement transform.
}
// Additionally, we can use the CompositionFrameId reported by the statistic
// to query timing-related information about that specific frame via the new
// composition timing API, such as when that frame showed up on screen.
// Note this is achieved using a separate API from the composition swapchain API, but
// using the composition frame ID reported in the composition swapchain API to
// properly specify which frame your application wants timing information from.
COMPOSITION_FRAME_TARGET_STATS frameTargetStats;
COMPOSITION_TARGET_STATS targetStats[4];
frameTargetStats.targetCount = ARRAYSIZE(targetStats);
frameTargetStats.targetStats = targetStats;
// Specify the frameId that we got from stats in order to pass to the call
// below and retrieve timing information about that frame.
frameTargetStats.frameId = frameId;
FAIL_FAST_IF_FAILED(DCompositionGetTargetStatistics(1, &frameTargetStats));
// If the frameTargetStats comes back with a 0 frameId, it means the frame isn't
// part of statistics. This might mean that it has expired out of
// DCompositionGetTargetStatistics history, but that call keeps a history buffer
// roughly equivalent to ~5 seconds worth of frame history, so if your application
// is processing statistics from the presentation manager relatively regularly,
// by all accounts it shouldn't worry about DCompositionGetTargetStatistics
// history expiring. The more likely scenario when this occurs is that it's too
// early, and that this frame isn't part of statistics YET. In that case, your application
// should defer processing for this frame, and try again later. For the purposes
// if sample brevity, we don't bother trying again here. A good method to use would
// be to add this present info to a list of presents that we haven't gotten target
// statistics for yet, and try again for all presents in that list any time we get
// a new PresentStatisticsKind_CompositionFrame for a future frame.
if (frameTargetStats.frameId == frameId)
{
// The targetCount will represent the count of outputs the given frame
// applied to.
frameTargetStats.targetCount;
// The targetTime corresponds to the wall clock QPC time DWM was
// targeting for the frame.
frameTargetStats.targetTime;
for (UINT i = 0; i < frameTargetStats.targetCount; i++)
{
const auto& targetStat = frameTargetStats.targetStats[i];
// The present time corresponds to the targeted present time of the composition
// frame.
targetStat.presentTime;
// The target ID corresponds to the LUID/VidPnSourceId/Unique ID for the given
// target.
targetStat.targetId;
// The completedStats convey information about the time a compositor frame was
// completed, which marks the time any of its associated composition swapchain API
// presents entered the displayed state. In particular, your application might wish
// to use the 'time' to know if a present showed at a time it expected.
targetStat.completedStats.presentCount;
targetStat.completedStats.refreshCount;
targetStat.completedStats.time;
// There is various other timing statistics information conveyed by
// DCompositionGetTargetStatistics.
}
}
}
break;
case PresentStatisticsKind_IndependentFlipFrame:
{
// Independent flip frame statistics describe a present that was shown via
// independent flip.
auto independentFlipFrameStatistics =
presentStatisticsItem.query<IIndependentFlipFramePresentStatistics>();
// Stats should come back for the present statistics item that we tagged earlier.
NT_ASSERT(independentFlipFrameStatistics->GetContentTag() == myPresentedContentTag);
// The driver-approved present duration describes the custom present duration that was
// approved by the driver and applied during the present. This is how, for example, media
// will know whether or not they got 24hz mode for their content if they requested it.
independentFlipFrameStatistics->GetPresentDuration();
// The displayed time is the time the present was confirmed to have been shown
// on screen.
independentFlipFrameStatistics->GetDisplayedTime();
// The adapter LUID/VidpnSource ID describe the output on which the present took
// place. Unlike the composition statistic above, we don't report a unique ID here
// because a monitor recycle would kick the presentation out of iflip.
independentFlipFrameStatistics->GetOutputAdapterLUID();
independentFlipFrameStatistics->GetOutputVidPnSourceId();
}
break;
}
}
Beispiel 17 – Verwenden einer Abstraktionsebene zur Darstellung mithilfe der neuen Kompositions-Swapchain-API oder DXGI aus Ihrer Anwendung
Angesichts der höheren System-/Treiberanforderungen der neuen Kompositions-Swapchain-API möchte Ihre Anwendung möglicherweise DXGI verwenden, wenn die neue API nicht unterstützt wird. Glücklicherweise ist es relativ einfach, eine Abstraktionsebene einzuführen, die die für die Präsentation verfügbare API verwendet. Im folgenden Beispiel wird veranschaulicht, wie Dies erreicht wird.
C++-Beispiel
// A base class presentation provider. We'll provide implementations using both DXGI and the new
// composition swapchain API, which the example will use based on what's supported.
class PresentationProvider
{
public:
virtual void GetBackBuffer(
_Out_ ID3D11Texture2D** ppBackBuffer) = 0;
virtual void Present(
_In_ SystemInterruptTime presentationTime) = 0;
virtual bool ReadStatistics(
_Out_ UINT* pPresentCount,
_Out_ UINT64* pSyncQPCTime) = 0;
virtual ID3D11Device* GetD3D11DeviceNoRef()
{
return m_d3dDevice.get();
}
protected:
com_ptr_failfast<ID3D11Device> m_d3dDevice;
};
// An implementation of PresentationProvider using a DXGI swapchain to provide presentation
// functionality.
class DXGIProvider :
public PresentationProvider
{
public:
DXGIProvider(
_In_ UINT width,
_In_ UINT height,
_In_ UINT bufferCount)
{
com_ptr_failfast<IDXGIAdapter> dxgiAdapter;
com_ptr_failfast<IDXGIFactory7> dxgiFactory;
com_ptr_failfast<IDXGISwapChain1> dxgiSwapchain;
com_ptr_failfast<ID3D11DeviceContext> d3dDeviceContext;
// Direct3D device creation flags.
UINT deviceCreationFlags =
D3D11_CREATE_DEVICE_BGRA_SUPPORT |
D3D11_CREATE_DEVICE_SINGLETHREADED;
// Create the Direct3D device.
FAIL_FAST_IF_FAILED(D3D11CreateDevice(
nullptr, // No adapter
D3D_DRIVER_TYPE_HARDWARE, // Hardware device
nullptr, // No module
deviceCreationFlags, // Device creation flags
nullptr, 0, // Highest available feature level
D3D11_SDK_VERSION, // API version
&m_d3dDevice, // Resulting interface pointer
nullptr, // Actual feature level
&d3dDeviceContext)); // Device context
// Make our way from the Direct3D device to the DXGI factory.
auto dxgiDevice = m_d3dDevice.query<IDXGIDevice>();
FAIL_FAST_IF_FAILED(dxgiDevice->GetParent(IID_PPV_ARGS(&dxgiAdapter)));
FAIL_FAST_IF_FAILED(dxgiAdapter->GetParent(IID_PPV_ARGS(&dxgiFactory)));
// Create a swapchain matching the desired parameters.
DXGI_SWAP_CHAIN_DESC1 desc = {};
desc.Width = width;
desc.Height = height;
desc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
desc.BufferUsage = DXGI_USAGE_RENDER_TARGET_OUTPUT;
desc.SampleDesc.Count = 1;
desc.SampleDesc.Quality = 0;
desc.BufferCount = bufferCount;
desc.Scaling = DXGI_SCALING_STRETCH;
desc.SwapEffect = DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL;
desc.AlphaMode = DXGI_ALPHA_MODE_PREMULTIPLIED;
FAIL_FAST_IF_FAILED(dxgiFactory->CreateSwapChainForComposition(
m_d3dDevice.get(),
&desc,
nullptr,
&dxgiSwapchain));
// Store the swapchain.
dxgiSwapchain.query_to(&m_swapchain);
}
void GetBackBuffer(
_Out_ ID3D11Texture2D** ppBackBuffer) override
{
// Get the backbuffer directly from the swapchain.
FAIL_FAST_IF_FAILED(m_swapchain->GetBuffer(
m_swapchain->GetCurrentBackBufferIndex(),
IID_PPV_ARGS(ppBackBuffer)));
}
void Present(
_In_ SystemInterruptTime presentationTime) override
{
// Convert the passed presentation time to a present interval. The implementation is
// not provided here, as there's a great deal of complexity around computing this
// most accurately, but it essentially boils down to taking the time from now and
// figuring out the number of vblanks that corresponds to that time duration.
UINT vblankIntervals = ComputePresentIntervalFromTime(presentationTime);
// Issue a present to the swapchain. If we wanted to allow for a time to be specified,
// code here could convert the time to a present duration, which could be passed here.
FAIL_FAST_IF_FAILED(m_swapchain->Present(vblankIntervals, 0));
}
bool ReadStatistics(
_Out_ UINT* pPresentCount,
_Out_ UINT64* pSyncQPCTime) override
{
// Zero our output parameters initially.
*pPresentCount = 0;
*pSyncQPCTime = 0;
// Grab frame statistics from the swapchain.
DXGI_FRAME_STATISTICS frameStatistics;
FAIL_FAST_IF_FAILED(m_swapchain->GetFrameStatistics(&frameStatistics));
// If the statistics have changed since our last read, then return the new information
// to the caller.
bool hasNewStats = false;
if (frameStatistics.PresentCount > m_lastPresentCount)
{
m_lastPresentCount = frameStatistics.PresentCount;
hasNewStats = true;
*pPresentCount = frameStatistics.PresentCount;
*pSyncQPCTime = frameStatistics.SyncQPCTime.QuadPart;
}
return hasNewStats;
}
private:
com_ptr_failfast<IDXGISwapChain4> m_swapchain;
UINT m_lastPresentCount = 0;
};
// An implementation of PresentationProvider using the composition swapchain API to provide
// presentation functionality.
class PresentationAPIProvider :
public PresentationProvider
{
public:
PresentationAPIProvider(
_In_ UINT width,
_In_ UINT height,
_In_ UINT bufferCount)
{
// Create the presentation manager and presentation surface using the function defined in a
// previous example.
MakePresentationManagerAndPresentationSurface(
&m_d3dDevice,
&m_presentationManager,
&m_presentationSurface,
m_presentationSurfaceHandle);
// Register for present statistics.
FAIL_FAST_IF_FAILED(m_presentationManager->EnablePresentStatisticsKind(
PresentStatisticsKind_CompositionFrame,
true));
// Get the statistics event from the presentation manager.
FAIL_FAST_IF_FAILED(m_presentationManager->GetPresentStatisticsAvailableEvent(
&m_statisticsAvailableEvent));
// Create and register the specified number of presentation buffers.
for (UINT i = 0; i < bufferCount; i++)
{
com_ptr_failfast<ID3D11Texture2D> texture;
com_ptr_failfast<IPresentationBuffer> presentationBuffer;
AddNewPresentationBuffer(
m_d3dDevice.get(),
m_presentationManager.get(),
width,
height,
&texture,
&presentationBuffer);
// Add the new presentation buffer and texture to our array.
m_textures.push_back(texture);
m_presentationBuffers.push_back(presentationBuffer);
// Store the available event for the presentation buffer.
unique_event availableEvent;
FAIL_FAST_IF_FAILED(presentationBuffer->GetAvailableEvent(&availableEvent));
m_bufferAvailableEvents.emplace_back(std::move(availableEvent));
}
}
void GetBackBuffer(
_Out_ ID3D11Texture2D** ppBackBuffer) override
{
// Query an available backbuffer using our available events.
DWORD waitIndex = WaitForMultipleObjects(
static_cast<UINT>(m_bufferAvailableEvents.size()),
reinterpret_cast<HANDLE*>(m_bufferAvailableEvents.data()),
FALSE,
INFINITE);
UINT bufferIndex = waitIndex - WAIT_OBJECT_0;
// Set the backbuffer to be the next presentation buffer.
FAIL_FAST_IF_FAILED(m_presentationSurface->SetBuffer(m_presentationBuffers[bufferIndex].get()));
// Return the backbuffer to the caller.
m_textures[bufferIndex].query_to(ppBackBuffer);
}
void Present(
_In_ SystemInterruptTime presentationTime) override
{
// Present at the targeted time.
m_presentationManager->SetTargetTime(presentationTime);
HRESULT hrPresent = m_presentationManager->Present();
if (hrPresent == PRESENTATION_ERROR_LOST)
{
// Our presentation manager has been lost. See previous examples regarding how to handle this.
return;
}
else
{
FAIL_FAST_IF_FAILED(hrPresent);
}
}
bool ReadStatistics(
_Out_ UINT* pPresentCount,
_Out_ UINT64* pSyncQPCTime) override
{
// Zero our out parameters initially.
*pPresentCount = 0;
*pSyncQPCTime = 0;
bool hasNewStats = false;
// Peek at the statistics available event state to see if we've got new statistics.
while (WaitForSingleObject(m_statisticsAvailableEvent.get(), 0) == WAIT_OBJECT_0)
{
// Pop a statistics item to process.
com_ptr_failfast<IPresentStatistics> statisticsItem;
FAIL_FAST_IF_FAILED(m_presentationManager->GetNextPresentStatistics(
&statisticsItem));
// If this is a composition frame stat, process it.
if (statisticsItem->GetKind() == PresentStatisticsKind_CompositionFrame)
{
// We've got new stats to report.
hasNewStats = true;
// Convert to composition frame statistic item.
auto frameStatisticsItem = statisticsItem.query<ICompositionFramePresentStatistics>();
// Query DirectComposition's target statistics API to determine the completed time.
COMPOSITION_FRAME_TARGET_STATS frameTargetStats;
COMPOSITION_TARGET_STATS targetStats[4];
frameTargetStats.targetCount = ARRAYSIZE(targetStats);
frameTargetStats.targetStats = targetStats;
// Specify the frameId we got from stats in order to pass to the call
// below and retrieve timing information about that frame.
frameTargetStats.frameId = frameStatisticsItem->GetCompositionFrameId();
FAIL_FAST_IF_FAILED(DCompositionGetTargetStatistics(1, &frameTargetStats));
// Return the statistics information for the first target.
*pPresentCount = static_cast<UINT>(frameStatisticsItem->GetPresentId());
*pSyncQPCTime = frameTargetStats.targetStats[0].completedStats.time;
// Note that there's a much richer variety of statistics information in the new
// API that can be used to infer much more than is possible with DXGI frame
// statistics.
}
}
return hasNewStats;
}
static bool IsSupportedOnSystem()
{
// Direct3D device creation flags. The composition swapchain API requires that applications disable internal
// driver threading optimizations, as these optimizations break synchronization of the API.
// If this flag isn't present, then the API will fail the call to create the presentation factory.
UINT deviceCreationFlags =
D3D11_CREATE_DEVICE_BGRA_SUPPORT |
D3D11_CREATE_DEVICE_SINGLETHREADED |
D3D11_CREATE_DEVICE_PREVENT_INTERNAL_THREADING_OPTIMIZATIONS;
// Create the Direct3D device.
com_ptr_failfast<ID3D11Device> d3dDevice;
com_ptr_failfast<ID3D11DeviceContext> d3dDeviceContext;
FAIL_FAST_IF_FAILED(D3D11CreateDevice(
nullptr, // No adapter
D3D_DRIVER_TYPE_HARDWARE, // Hardware device
nullptr, // No module
deviceCreationFlags, // Device creation flags
nullptr, 0, // Highest available feature level
D3D11_SDK_VERSION, // API version
&d3dDevice, // Resulting interface pointer
nullptr, // Actual feature level
&d3dDeviceContext)); // Device context
// Call the composition swapchain API export to create the presentation factory.
com_ptr_failfast<IPresentationFactory> presentationFactory;
FAIL_FAST_IF_FAILED(CreatePresentationFactory(
d3dDevice.get(),
IID_PPV_ARGS(&presentationFactory)));
// Now determine whether the system is capable of supporting the composition swapchain API based
// on the capability that's reported by the presentation factory.
return presentationFactory->IsPresentationSupported();
}
private:
com_ptr_failfast<IPresentationManager> m_presentationManager;
com_ptr_failfast<IPresentationSurface> m_presentationSurface;
vector<com_ptr_failfast<ID3D11Texture2D>> m_textures;
vector<com_ptr_failfast<IPresentationBuffer>> m_presentationBuffers;
vector<unique_event> m_bufferAvailableEvents;
unique_handle m_presentationSurfaceHandle;
unique_event m_statisticsAvailableEvent;
};
void DXGIOrPresentationAPIExample()
{
// Get the current system time. We'll base our 'PresentAt' time on this result.
SystemInterruptTime currentTime;
QueryInterruptTimePrecise(¤tTime.value);
// Track a time we'll be presenting at below. Default to the current time, then increment by
// 1/10th of a second every present.
auto presentTime = currentTime;
// Allocate a presentation provider using the composition swapchain API if it is supported;
// otherwise fall back to DXGI.
unique_ptr<PresentationProvider> presentationProvider;
if (PresentationAPIProvider::IsSupportedOnSystem())
{
presentationProvider = std::make_unique<PresentationAPIProvider>(
500, // Buffer width
500, // Buffer height
6); // Number of buffers
}
else
{
// System doesn't support the composition swapchain API. Fall back to DXGI.
presentationProvider = std::make_unique<DXGIProvider>(
500, // Buffer width
500, // Buffer height
6); // Number of buffers
}
// Present 50 times.
constexpr UINT numPresents = 50;
for (UINT i = 0; i < 50; i++)
{
// Advance our present time 1/10th of a second in the future.
presentTime.value += 1'000'000;
// Call the presentation provider to get a backbuffer to render to.
com_ptr_failfast<ID3D11Texture2D> backBuffer;
presentationProvider->GetBackBuffer(&backBuffer);
// Render to the backbuffer.
DrawColorToSurface(
presentationProvider->GetD3D11DeviceNoRef(),
backBuffer,
1.0f, // red
0.0f, // green
0.0f); // blue
// Present the backbuffer.
presentationProvider->Present(presentTime);
// Process statistics.
bool hasNewStats;
UINT64 presentTime;
UINT presentCount;
hasNewStats = presentationProvider->ReadStatistics(
&presentCount,
&presentTime);
if (hasNewStats)
{
// Process these statistics however your application wishes.
}
}
}