Método IDirect3DDevice9::StretchRect (d3d9.h)

Artículo
08/23/2023

Copie el contenido del rectángulo de origen en el rectángulo de destino. La copia puede estirar y filtrar el rectángulo de origen. Esta función se usa a menudo para cambiar la relación de aspecto de una secuencia de vídeo.

Sintaxis

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

Parámetros

[in] pSourceSurface

Tipo: IDirect3DSurface9*

Puntero a la superficie de origen. Consulta IDirect3DSurface9.

[in] pSourceRect

Tipo: const RECT*

Puntero al rectángulo de origen. Un valor NULL para este parámetro hace que se use toda la superficie de origen.

[in] pDestSurface

Tipo: IDirect3DSurface9*

Puntero a la superficie de destino. Consulta IDirect3DSurface9.

[in] pDestRect

Tipo: const RECT*

Puntero al rectángulo de destino. Un valor NULL para este parámetro hace que se use toda la superficie de destino.

[in] Filter

Tipo: D3DTEXTUREFILTERTYPE

Tipo de filtro. Los valores permitidos son D3DTEXF_NONE, D3DTEXF_POINT o D3DTEXF_LINEAR. Para obtener más información, vea D3DTEXTUREFILTERTYPE.

Valor devuelto

Tipo: HRESULT

Si el método se ejecuta correctamente, el valor devuelto es D3D_OK. Si se produce un error en el método, el valor devuelto puede ser: D3DERR_INVALIDCALL.

Comentarios

Restricciones de StretchRect

La compatibilidad con controladores varía. Consulte la sección sobre compatibilidad con controladores (a continuación) para ver qué controladores admiten qué formatos de origen y destino.
Las superficies de origen y destino deben crearse en el grupo de memoria predeterminado.
Si se especifica el filtrado, debe establecer los límites de filtro adecuados (consulte StretchRectFilterCaps en D3DCAPS9).
La extensión no se admite entre rectángulos de origen y destino en la misma superficie.
La extensión no se admite si la superficie de destino es una superficie sin formato fuera de la pantalla, pero el origen no lo es.
Muchos no se extienden entre rectángulos de origen y destino si alguna de las superficies está en un formato comprimido (consulte Uso de texturas comprimidas (Direct3D 9)).
La extensión admite la conversión de espacio de color de YUV a RGBA de alta precisión. Dado que la compatibilidad con la conversión de colores no es compatible con la emulación de software, use IDirect3D9::CheckDeviceFormatConversion para probar el hardware para la compatibilidad con la conversión de colores.
Si la superficie de origen o destino es una superficie de textura (o una superficie de textura de cubo), debes usar un controlador direct3D 9 que admita D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES (consulta D3DDEVCAPS2).

Restricciones adicionales para superficies de galería de símbolos y profundidad

Las superficies de origen y destino deben ser superficies de galería de símbolos de profundidad sin formato (no texturas) (vea IDirect3DDevice9::CreateDepthStencilSurface).
Ninguna de las superficies se puede descartar.
Toda la superficie debe copiarse (es decir, no se permiten copias de sub rectángulo).
No se admite la conversión, el ajuste y la reducción de formato.
No se puede llamar a StretchRect dentro de un par BeginScene/EndScene.

Uso de StretchRect para reducir el tamaño de un rendertarget multisample

Puede usar StretchRect para copiar de un rendertarget a otro. Si el rendertarget de origen es multimuestreo, se reduce el muestreo del rendertarget de origen. Por ejemplo, podría:

Cree un rendertarget multimuestreo.
Cree un segundo rendertarget con el mismo tamaño, que no sea multimuestreo.
Copie (mediante StretchRect el rendertarget multisample en el segundo rendertarget.

Tenga en cuenta que el uso de la superficie adicional implicada en el uso de StretchRect para reducir un rendertarget multisample dará como resultado un impacto en el rendimiento.

Compatibilidad de controlador

Hay muchas restricciones en cuanto a qué combinaciones de superficies son válidas para StretchRect. Los factores incluyen si el controlador es un controlador de Direct3D 9 o anterior, y si la operación dará lugar a un ajuste o reducción. Dado que no se espera que las aplicaciones reconozcan si el controlador es un controlador de Direct3D 9 o no, el tiempo de ejecución establecerá automáticamente un nuevo límite, D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES límite (consulte D3DDEVCAPS2), para controladores de Nivel 9 de Direct3D y versiones posteriores.

Controlador DirectX 8 (sin extensión)
		Formatos dest
		Textura	Textura RT	RT	Sin formato en pantalla
Formatos Src	Textura	No	No	No	No
	Textura RT	No	Sí	Sí	No
	RT	No	Sí	Sí	No
	Sin formato en pantalla	Sí	Sí	Sí	Sí

Controlador DirectX 8 (estirado)
		Formatos dest
		Textura	Textura RT	RT	Sin formato en pantalla
Formatos Src	Textura	No	No	No	No
	Textura RT	No	No	No	No
	RT	No	Sí	Sí	No
	Sin formato de pantalla	No	Sí	Sí	No

Controlador direct3D 9 (sin estirar)
		Formatos dest
		Textura	Textura RT	RT	Sin formato de pantalla
Formatos Src	Textura	No	Sí	Sí	No
	Textura RT	No	Sí	Sí	No
	RT	No	Sí	Sí	No
	Sin formato de pantalla	No	Sí	Sí	Sí