ICompositionDrawingSurfaceInterop2::CopySurface-Methode (windows.ui.composition.interop.h)
Liest den Inhalt einer Kompositionszeichnungsoberfläche (oder einer virtuellen Kompositionszeichnungsoberfläche) zurück.
Syntax
HRESULT CopySurface(
[in] IUnknown *destinationResource,
[in] int destinationOffsetX,
[in] int destinationOffsetY,
[in] const RECT *sourceRectangle
);
Parameter
[in] destinationResource
Typ: IUnknown*
Stellt die Direct3D-Textur dar, die die Kopie empfängt. Sie müssen diese Ressource auf demselben Direct3D-Gerät erstellt haben, das dem CompositionGraphicsDevice zugeordnet ist, das zum Erstellen der Zeichnungsoberfläche der Quellkomposition (oder der virtuellen Zeichnungsoberfläche der Komposition) verwendet wurde.
[in] destinationOffsetX
Typ: int
Die x-Koordinate eines Offsets (in destinationResource), in dem die Kopie ausgeführt wird. Durch den Kopiervorgang werden keine Pixel oberhalb oder links von diesem Offset geändert. Das Argument kann nicht negativ sein.
[in] destinationOffsetY
Typ: int
Die y-Koordinate eines Offsets (in destinationResource), in dem die Kopie ausgeführt wird. Durch den Kopiervorgang werden keine Pixel oberhalb oder links von diesem Offset geändert. Das Argument kann nicht negativ sein.
[in] sourceRectangle
Typ: const RECT*
Ein optionaler Zeiger auf eine konstante RECT , die das Zu kopierende Rechteck auf der Quelloberfläche darstellt. Das Rechteck darf die Grenzen der Quelloberfläche nicht überschreiten. Damit genügend Platz zum Empfangen der angeforderten Pixel vorhanden ist, muss die Zielressource mindestens so viele Pixel wie die Parameter destinationOffsetX und Y sowie die Breite/Höhe dieses Rechtecks aufweisen.
Wenn dieser Parameter NULL ist, wird die gesamte Quelloberfläche kopiert (und die Quelloberflächengröße wird verwendet, um die Größe der Zielressource zu überprüfen).
Rückgabewert
Typ: HRESULT
S_OK bei erfolgreicher Ausführung gibt andernfalls einen HRESULT-Fehlercode zurück, der den Grund für den Fehler angibt. Weitere Informationen finden Sie unter COM-Fehlercodes (UI, Audio, DirectX, Codec)..
Hinweise
Um eine Direct2D- oder Direct3D-Oberfläche für die Verwendung mit Windows.UI.Composition zu erstellen, verwenden Sie die Interoperationsschnittstellen für die Kompositionszeichnungsoberfläche . Mit der CopySurface-Methode können Sie den Inhalt einer Kompositionszeichnungsoberfläche (oder einer virtuellen Zeichnungsoberfläche der Komposition) zurücklesen. CopySurface ist eine synchrone und sofortige Kopie von einem Teil des Videospeichers in einen anderen; Sie müssen commit nicht aufrufen.
Für eine beliebige Kompositionszeichnungsoberfläche (oder eine virtuelle Zeichnungsoberfläche der Komposition) kann Ihre Anwendung ICompositionDrawingSurfaceInterop2 abfragen und CopySurface für diese Schnittstelle aufrufen.
Sie können CopySurface nur aufrufen, wenn keine ausstehenden Updates für Oberflächen vorhanden sind, die zu derselben CompositionGraphicsDevice wie die Quelloberfläche gehören (ICompositionDrawingSurfaceInterop::BeginDraw hat die gleiche Anforderung). Es ist auch illegal, CopySurface auf einer nicht virtuellen Kompositionszeichnungsoberfläche aufzurufen, die nie aktualisiert wurde, da derEn Pixelinhalt nicht definiert ist. Für virtuelle Oberflächen ist es möglich, ein Quellrechteck anzugeben, das nicht initialisierte Bereiche der Oberfläche überschneidet, da sie nur spärlich zugeordnet sind. In diesem Fall ist der Aufruf legal, aber das Ergebnis der Kopie für diese nicht initialisierten Regionen ist nicht definiert.
Hinweis
Diese Schnittstelle ist auf Windows 10, Version 1903 (10.0; Build 18362), aber es ist nicht in der windows.ui.composition.interop.h Headerdatei für diese Version des Windows Software Development Kit (SDK) definiert. Wenn Sie zuerst einen Zeiger auf eine ICompositionDrawingSurfaceInterop-Schnittstelle erhalten, können Sie diese (über QueryInterface) nach einem Zeiger auf eine ICompositionDrawingSurfaceInterop2-Schnittstelle abfragen.
Beispiele
Für dieses Szenario stellen wir uns ein Framework vor, das CompositionDrawingSurface verwendet, um benutzerdefinierte Inhalte zu rendern und in einer visuellen Struktur zu erstellen, die vom Framework verwaltet wird. Das Framework implementiert einen Modus mit niedrigen Ressourcen (z. B. während des Minimierens oder Anhaltens der Anwendung). In diesem Modus gibt das Framework die meisten Kompositionsobjekte frei, einschließlich aller Oberflächen. Bevor es jedoch jede Oberfläche freigibt, extrahiert das Framework die Pixel und komprimiert sie (z. B. mithilfe des PNG-Codecs), sodass es sie später neu konstituieren kann, ohne in den Anwendungscode zurückrufen zu müssen. Dieses Codebeispiel zeigt eine Hilfsfunktion, die das Framework möglicherweise implementiert, um jede Oberfläche zu verarbeiten.
HRESULT CompressSurface(_In_ ICompositionDrawingSurface* surface)
{
// Get the interop interface.
ComPtr<ICompositionDrawingSurfaceInterop2> surfaceInterop;
RETURN_IF_FAILED(surface.As(&surfaceInterop));
// Allocate a staging surface of equal size to the surface to compress.
SizeInt32 size;
RETURN_IF_FAILED(surface->get_Size(&size));
// Create a staging texture to receive a copy of the pixels.
ComPtr<ID3D11Texture2D> stagingTexture;
RETURN_IF_FAILED(CreateStagingTexture(size, stagingTexture.GetAddressOf()));
// Copy the pixels out.
RETURN_IF_FAILED(surfaceInterop->CopySurface(stagingTexture.get(), 0, 0, nullptr));
// Compress the retrieved pixels.
RETURN_IF_FAILED(CompressTexturePixels(stagingTexture.get()));
return S_OK;
}
HRESULT CreateStagingTexture(const SizeInt32& size, _Outptr_ ID3D11Texture2D** texture)
{
D3D11_TEXTURE2D_DESC surfaceDesc;
surfaceDesc.Width = size.Width;
surfaceDesc.Height = size.Height;
surfaceDesc.MipLevels = 1;
surfaceDesc.ArraySize = 1;
surfaceDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM;
surfaceDesc.SampleDesc.Count = 1;
surfaceDesc.SampleDesc.Quality = 0;
surfaceDesc.Usage = D3D11_USAGE_STAGING;
surfaceDesc.BindFlags = 0;
surfaceDesc.CPUAccessFlags = D3D11_CPU_ACCESS_READ;
surfaceDesc.MiscFlags = 0;
RETURN_IF_FAILED(g_d3d11Device->CreateTexture2D(surfaceDesc, false, texture));
return S_OK;
}
HRESULT CompressTexturePixels(_In_ ID3D11Texture2D* texture)
{
// ...
// Map the texture, feed the pixels to WIC...
// ...
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 10, Version 2004 (10.0; Build 19041) |
| Unterstützte Mindestversion (Server) | Windows Server, Version 2004 (10.0; Build 19041) |
| Zielplattform | Windows |
| Kopfzeile | windows.ui.composition.interop.h |