IDirect3DDevice9::StretchRect-Methode (d3d9helper.h)

Artikel
08/23/2023

Kopieren Sie den Inhalt des Quellrechtecks in das Zielrechteck. Das Quellrechteck kann durch die Kopie gestreckt und gefiltert werden. Diese Funktion wird häufig verwendet, um das Seitenverhältnis eines Videostreams zu ändern.

Syntax

HRESULT StretchRect(
  [in] IDirect3DSurface9    *pSourceSurface,
  [in] const RECT           *pSourceRect,
  [in] IDirect3DSurface9    *pDestSurface,
  [in] const RECT           *pDestRect,
  [in] D3DTEXTUREFILTERTYPE Filter
);

Parameter

[in] pSourceSurface

Typ: IDirect3DSurface9*

Zeiger auf die Quelloberfläche. Siehe IDirect3DSurface9.

[in] pSourceRect

Typ: const RECT*

Zeiger auf das Quellrechteck. Ein NULL-Wert für diesen Parameter bewirkt, dass die gesamte Quelloberfläche verwendet wird.

[in] pDestSurface

Typ: IDirect3DSurface9*

Zeiger auf die Zieloberfläche. Siehe IDirect3DSurface9.

[in] pDestRect

Typ: const RECT*

Zeiger auf das Zielrechteck. Ein NULL-Wert für diesen Parameter bewirkt, dass die gesamte Zieloberfläche verwendet wird.

[in] Filter

Typ: D3DTEXTUREFILTERTYPE

Filtertyp. Zulässige Werte sind D3DTEXF_NONE, D3DTEXF_POINT oder D3DTEXF_LINEAR. Weitere Informationen finden Sie unter D3DTEXTUREFILTERTYPE.

Rückgabewert

Typ: HRESULT

Wenn die Methode erfolgreich ist, wird der Rückgabewert D3D_OK. Wenn die Methode fehlschlägt, kann der Rückgabewert folgendes sein: D3DERR_INVALIDCALL.

Hinweise

StretchRect-Einschränkungen

Die Treiberunterstützung variiert. Im Abschnitt zur Treiberunterstützung (unten) erfahren Sie, welche Treiber welche Quell- und Zielformate unterstützen.
Die Quell- und Zieloberflächen müssen im Standardspeicherpool erstellt werden.
Wenn Filterung angegeben ist, müssen Sie die entsprechenden Filterkappen festlegen (siehe StretchRectFilterCaps in D3DCAPS9).
Das Dehnen zwischen Quell- und Zielrechtecken auf derselben Oberfläche wird nicht unterstützt.
Die Dehnung wird nicht unterstützt, wenn es sich bei der Zieloberfläche um eine einfache Oberfläche außerhalb des Bildschirms handelt, die Quelle jedoch nicht.
Sie können sich nicht zwischen Quell- und Zielrechtecken erstrecken, wenn beide Oberflächen in einem komprimierten Format vorliegen (siehe Verwenden komprimierter Texturen (Direct3D 9)).
Das Dehnen unterstützt nur die Farbraumkonvertierung von YUV in hochgenaue RGBA. Da die Unterstützung für die Farbkonvertierung von der Softwareemulation nicht unterstützt wird, verwenden Sie IDirect3D9::CheckDeviceFormatConversion , um die Hardware auf die Unterstützung der Farbkonvertierung zu testen.
Wenn die Quell- oder Zieloberfläche eine Texturoberfläche (oder eine Cubetexturoberfläche) ist, müssen Sie einen Direct3D 9-Treiber verwenden, der D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES unterstützt (siehe D3DDEVCAPS2).

Zusätzliche Einschränkungen für Tiefen- und Schablonenoberflächen

Die Quell- und Zieloberflächen müssen Schablonenflächen mit einfacher Tiefe (nicht Texturen) sein (siehe IDirect3DDevice9::CreateDepthStencilSurface).
Keine der Oberflächen kann verworfen werden.
Die gesamte Oberfläche muss kopiert werden (das heißt: Subrechteckkopien sind nicht zulässig).
Formatkonvertierung, Dehnung und Verkleinerung werden nicht unterstützt.
StretchRect kann nicht innerhalb eines BeginScene/EndScene-Paares aufgerufen werden.

Verwenden von StretchRect zum Herunterstempeln eines Multisample-Rendertargets

Sie können StretchRect verwenden, um von einem Rendertarget in einen anderen zu kopieren. Wenn das Quellrenderget multisampled ist, führt dies zu einem Downsampling des Quellrendergets. Für instance könnten Sie:

Erstellen Sie einen mehrstufigen Rendertarget.
Erstellen Sie ein zweites Rendertarget der gleichen Größe, das nicht multisampled ist.
Kopieren Sie (mithilfe von StretchRect das multisample rendertarget in das zweite rendertarget.

Beachten Sie, dass die Verwendung der zusätzlichen Oberfläche, die bei der Verwendung von StretchRect zum Downsample eines Multisample-Rendertargets erforderlich ist, zu einem Leistungstreffer führt.

Treiberunterstützung

Es gibt viele Einschränkungen, welche Oberflächenkombinationen für StretchRect gültig sind. Faktoren umfassen, ob der Treiber ein Direct3D 9-Treiber oder älter ist und ob der Vorgang zu einer Dehnung/Verkleinerung führt. Da von Anwendungen nicht erwartet wird, dass sie erkennen, ob es sich beim Treiber um einen Direct3D 9-Treiber handelt oder nicht, legt die Runtime automatisch eine neue Obergrenze D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES Für Direct3D 9-Level-Treiber und höher fest.

DirectX 8-Treiber (keine Dehnung)
		Dest-Formate
		Struktur	RT-Textur	RT	Außerhalb des Bildschirms
Src-Formate	Struktur	Nein	Nein	Nein	Nein
	RT-Textur	Nein	Ja	Ja	Nein
	RT	Nein	Ja	Ja	Nein
	Außerhalb des Bildschirms	Ja	Ja	Ja	Ja

DirectX 8-Treiber (Dehnung)
		Dest-Formate
		Struktur	RT-Textur	RT	Außerhalb des Bildschirms
Src-Formate	Struktur	Nein	Nein	Nein	Nein
	RT-Textur	Nein	Nein	Nein	Nein
	RT	Nein	Ja	Ja	Nein
	Außerhalb des Bildschirms	Nein	Ja	Ja	Nein

Direct3D 9-Treiber (keine Dehnung)
		Dest-Formate
		Struktur	RT-Textur	RT	Außerhalb des Bildschirms
Src-Formate	Struktur	Nein	Ja	Ja	Nein
	RT-Textur	Nein	Ja	Ja	Nein
	RT	Nein	Ja	Ja	Nein
	Außerhalb des Bildschirms	Nein	Ja	Ja	Ja

Direct3D 9-Treiber (Dehnung)
		Dest-Formate
		Struktur	RT-Textur	RT	Außerhalb des Bildschirms
Src-Formate	Struktur	Nein	Ja	Ja	Nein
	RT-Textur	Nein	Ja	Ja	Nein
	RT	Nein	Ja	Ja	Nein
	Außerhalb des Bildschirms	Nein	Ja	Ja	Nein