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

Artículo
08/23/2023

Copie el contenido del rectángulo de origen en el rectángulo de destino. El rectángulo de origen se puede estirar y filtrar por la copia. 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. Vea 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. Vea 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 realiza 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 los 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).
No se admite la extensión entre rectángulos de origen y destino en la misma superficie.
No se admite la extensión 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 solo admite la conversión de espacio en color de YUV a RGBA de alta precisión. Puesto que la compatibilidad con la conversión de color no es compatible con la emulación de software, use IDirect3D9::CheckDeviceFormatConversion para probar el hardware para la compatibilidad con la conversión de color.
Si la superficie de origen o destino es una superficie de textura (o una superficie de textura de cubo), debe usar un controlador Direct3D 9 que admita D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES (consulte 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 admiten la conversión de formato, el ajuste y la reducción.
StretchRect no se puede llamar dentro de un par BeginScene/EndScene.

Uso de StretchRect para reducir 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 (con 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 más antiguo, y si la operación dará como resultado el ajuste o la reducción. Puesto 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 límite nuevo, D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES límite (consulte D3DDEVCAPS2), para los controladores de Nivel 9 de Direct3D y versiones posteriores.

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

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

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