DirectXTex

Biblioteca de procesamiento de texturas DirectXTex

http://go.microsoft.com/fwlink/?LinkId=248926

Copyright (c) Microsoft Corporation.

28 de octubre de 2024

Este paquete contiene DirectXTex, una biblioteca de código fuente compartida para leer y escribir archivos .DDS y realizar varias operaciones de procesamiento de contenido de textura, incluido cambio de tamaño, conversión de formato, generación de mapas MIP, compresión de bloques para recursos de textura en tiempo de ejecución de Direct3D y mapa de altura a normal. conversión de mapas. Esta biblioteca utiliza las API del componente de imagen de Windows (WIC). También incluye lectores y escritores .TGA y .HDR ya que estos formatos de archivos de imagen se usan comúnmente para canales de procesamiento de contenido de texturas, pero actualmente no son compatibles con un códec WIC integrado.

Este código está diseñado para compilarse con Visual Studio 2019 (16.11), Visual Studio 2022, clang para Windows v12 o posterior, o MinGW 12.2. Se requiere el uso del SDK de actualización de Windows 10 de mayo de 2020 (19041) o posterior para Visual Studio. También se puede crear para el subsistema de Windows para Linux utilizando GCC 11 o posterior.

Estos componentes están diseñados para funcionar sin requerir ningún contenido del SDK de DirectX heredado. Para obtener más información, consulte ¿Dónde está el SDK de DirectX?

Diseño del directorio

• DirectXTex

  • Este contiene la biblioteca DirectXTex. Esto incluye un lector y escritor DDS con todas las funciones que incluye conversiones de formatos heredados, un lector y escritor TGA, un lector y escritor HDR, un lector y escritor de mapas de bits basado en WIC (BMP, JPEG, PNG, TIFF y HD Photo) y Varias funciones de procesamiento de texturas. Está destinado principalmente al uso de herramientas.

La mayoría de los archivos de encabezado aquí están destinados únicamente a la implementación interna de la biblioteca ( BC.h , BCDirectCompute.h , DDS.h , DirectXTexP.h , etc.). Sólo DirectXTex.h y DirectXTex.inl están pensados ​​como encabezado "público" de la biblioteca.

• Auxiliary

  • Contiene archivos fuente opcionales para la biblioteca DirectXTex, como funciones de carga de adaptadores usando la biblioteca OpenEXR, extensiones de mosaico de texturas de Xbox, etc.

• Common

  • Contiene encabezados de origen compartidos utilizados por la biblioteca y las herramientas de DirectXTex.

• Texconv

  • Este ejemplo de DirectXTex es una implementación de la utilidad de textura de línea de comandos texconv ​​del SDK de DirectX que utiliza DirectXTex en lugar de D3DX.

    Admite los mismos argumentos que la utilidad DirectX SDK heredada de Texture Conversion Tool Extended ( texconvex.exe ). Las principales diferencias son que los argumentos -10 y -11 no son aplicables y los nombres de los filtros ( POINT , LINEAR , CUBIC , FANT o BOX , TRIANGLE , *_DITHER , *_DITHER_DIFFUSION ). Esto también incluye compatibilidad con el formato de mapa de bits JPEG XR (Foto HD).

• Texassemble

  • Este ejemplo de DirectXTex es una utilidad de línea de comandos para crear mapas de cubos, mapas de volumen o matrices de texturas a partir de un conjunto de archivos de imágenes de entrada individuales.

• Texdiag

  • Este ejemplo de DirectXTex es una utilidad de línea de comandos para analizar contenidos de imágenes, principalmente con fines de depuración.

• DDSView

  • Este ejemplo de DirectXTex es un visor sencillo basado en Direct3D 11 para archivos DDS. Para texturas de matriz o mapas de volumen, las teclas del teclado "<" y ">" mostrarán diferentes imágenes contenidas en el DDS. Las teclas "1" a "0" también se pueden utilizar para saltar a un índice de imagen específico.

• DDSTextureLoader

  • Contiene una versión optimizada del código de carga de textura DDSWithoutD3DX11 de muestra del SDK de DirectX heredado para un cargador DDS de tiempo de ejecución simple y liviano. Hay versiones para Direct3D 9, Direct3D 11 y Direct3D 12. Esto no realiza conversiones de datos de píxeles en tiempo de ejecución. Esto es ideal para el uso en tiempo de ejecución y admite el complemento completo de recursos de textura Direct3D (1D, 2D, mapas de volumen, mapas de cubos, niveles de mapas MIP, matrices de texturas, formatos BC, etc.).

• ScreenGrab

  • Contiene módulos de escritura de texturas para Direct3D 9, Direct3D 11 y Direct3D 12 destinados principalmente a crear capturas de pantalla. Las imágenes se escriben como DDS o como formato de archivo de imagen utilizando WIC.

• WICTextureLoader

  • Contiene un cargador de texturas 2D Direct3D 9, Direct3D 11 y Direct3D 12 que utiliza WIC para cargar un mapa de bits (BMP, JPEG, PNG, HD Photo u otro contenedor de archivos compatible con WIC), cambiar el tamaño si es necesario según el nivel de función actual (o por parámetro explícito), convierta el formato a DXGI_FORMAT si es necesario y luego cree una textura 2D. Tenga en cuenta que esto no admite texturas 1D, texturas de volumen, mapas de cubos ni matrices de texturas. Se recomienda DDSTextureLoader para texturas completamente "precocidas" para obtener el máximo rendimiento y calidad de imagen, pero este cargador puede ser útil para crear texturas 2D simples a partir de archivos de imagen estándar en tiempo de ejecución.

DDSTextureLoader11, ScreenGrab11 y WICTextureLoader11 son versiones "independientes" de los mismos módulos proporcionados en el kit de herramientas DirectX para DX11.

DDSTextureLoader12, ScreenGrab12 y WICTextureLoader12 son versiones "independientes" de los mismos módulos proporcionados en el kit de herramientas DirectX para DX12.

• build

  • Contiene archivos YAML para las canalizaciones de compilación junto con algunos archivos de compilación y scripts diversos.

Documentación

La documentación está disponible en la wiki de GitHub.

Avisos

Todo el contenido y el código fuente de este paquete están sujetos a los términos de la licencia MIT.

Para obtener la última versión de DirectXTex, informes de errores, etc., visite el sitio del proyecto en GitHub.

Notas de la versión

PARA OBTENER AVISOS DE SEGURIDAD, consulte GitHub.

Para obtener un historial de cambios completo, consulte CHANGELOG.md.

• A partir de la versión de julio de 2022, el parámetro bool forceSRGB para las funciones CreateTextureEx y CreateShaderResourceViewEx ahora es un parámetro de marca de máscara de bits de enumeración con tipo CREATETEX_FLAGS . Esto puede tener un impacto de cambio importante en el código del cliente. Reemplace true con CREATETEX_FORCE_SRGB y false con CREATETEX_DEFAULT .

• A partir de la versión de junio de 2020, esta biblioteca utiliza indicadores de máscara de bits de enumeración escrita según la recomendación de la sección 17.5.2.1.3 del estándar C++ Tipos de máscara de bits. Esto es coherente con el uso que hace Direct3D 12 de la macro DEFINE_ENUM_FLAG_OPERATORS . Esto puede tener impactos de cambios importantes en el código del cliente:

  • No puede pasar el literal 0 como valor de sus banderas. En su lugar, debe utilizar el valor de enumeración predeterminado apropiado: CP_FLAGS_NONE , DDS_FLAGS_NONE , WIC_FLAGS_NONE , TEX_FR_ROTATE0 , TEX_FILTER_DEFAULT , TEX_FILTER_DEFAULT , TEX_FILTER_DEFAULT , CNMAP_DEFAULT o CNMAP_DEFAULT .

  • Utilice el tipo de enumeración en lugar de DWORD si crea valores de indicadores localmente con operaciones de máscara de bits. Por ejemplo, DDS_FLAGS flags = DDS_FLAGS_NONE; if (...) flags |= DDS_FLAGS_EXPAND_LUMINANCE;

  • En los casos en que algunas de las banderas se superpongan, puede utilizar el | para combinar los tipos relevantes: los modos de filtro TEX_FILTER_FLAGS se combinan con WIC_FLAGS , los indicadores TEX_FILTER_FLAGS sRGB se combinan con TEX_PMALPHA_FLAGS o TEX_COMPRESS_FLAGS . No se definen otros operadores bit a bit. Por ejemplo, WIC_FLAGS wicFlags = WIC_FLAGS_NONE | TEX_FILTER_CUBIC;

• WICTextureLoader no puede cargar archivos .TGA o .HDR a menos que el sistema tenga instalado un códec WIC de terceros. Debe utilizar la biblioteca DirectXTex para admitir el formato de archivo TGA/HDR sin depender de un códec WIC adicional.

• Los proyectos UWP y el proyecto de escritorio clásico Win10 incluyen configuraciones para la plataforma ARM64. Para crearlos es necesario instalar el conjunto de herramientas ARM64.

• Para el desarrollo de ARM64/AArch64, se recomienda encarecidamente el compilador VS 2022 en lugar del conjunto de herramientas VS 2019. El SDK de Windows (26100 o posterior) no es compatible con VS 2019 para Win32 en desarrollo ARM64. Tenga en cuenta que la plataforma ARM32/AArch32 está en desuso .

• Cuando se utiliza clang/LLVM para la plataforma ARM64/AArch64, se requiere el SDK de Windows 11 (22000) o posterior.

• El script CompileShaders.cmd debe tener finales de línea al estilo de Windows (CRLF). Si se cambia a finales de línea estilo Linux (LF), es posible que no se puedan crear todos los sombreadores necesarios.

• A partir de la versión de octubre de 2024, las herramientas de línea de comandos también admiten opciones largas de estilo GNU usando -- . Todos los modificadores existentes continúan funcionando, pero algunas de - opciones ahora están obsoletas según esta tabla:

ensamblar texto		texconv		textodiag
-mapa de tonos	--mapa de tonos	-badtails	--malas colas	-badtails	--malas colas
-bgcolor	--gif-bg-color	-fixbc4x4	--arreglar-bc-4x4	-ignoremips	--ignorar-mips
-swizzle	--swizzle	-ignoremips	--ignorar-mips	-permisivo	--permisivo
-stripmips	--strip-mips	-invertir	--invertir-y	-objetivox	--objetivo-x
		-mantener cobertura	--mantener-cobertura
		-permisivo	--permisivo
		-reconstruir	--reconstruir-z
		-rotarcolor	--rotar-color
		-singleproc	--procesamiento único
		-swizzle	--swizzle
		-tgazeroalfa	--tga-cero-alfa
		-momento	--momento
		-mapa de tonos	--mapa de tonos
		-sin wiclos	--wic-sin pérdidas
		-wicmulti	--wic-multitrama
		-x2bias	--sesgo x2

Apoyo

Si tiene preguntas, considere usar Stack Overflow con la etiqueta directxtk o DirectX Discord Server en el canal dx12-developers o dx9-dx11-developers .

Para informes de errores y solicitudes de funciones, utilice los problemas de GitHub para este proyecto.

Contribuyendo

Este proyecto agradece contribuciones y sugerencias. La mayoría de las contribuciones requieren que usted acepte un Acuerdo de licencia de colaborador (CLA) que declara que tiene derecho a otorgarnos, y de hecho lo hace, los derechos para usar su contribución. Para obtener más detalles, visite https://cla.opensource.microsoft.com.

Cuando envía una solicitud de extracción, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar el PR de manera adecuada (por ejemplo, verificación de estado, comentario). Simplemente siga las instrucciones proporcionadas por el bot. Solo necesitarás hacer esto una vez en todos los repositorios que utilicen nuestro CLA.

Las pruebas de nuevas funciones también deben enviarse como PR al repositorio de Test Suite.

Código de conducta

Este proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas frecuentes sobre el Código de conducta o comuníquese con [email protected] si tiene alguna pregunta o comentario adicional.

Marcas registradas

Este proyecto puede contener marcas comerciales o logotipos de proyectos, productos o servicios. El uso autorizado de las marcas comerciales o logotipos de Microsoft está sujeto y debe seguir las Pautas de marcas y marcas comerciales de Microsoft. El uso de marcas comerciales o logotipos de Microsoft en versiones modificadas de este proyecto no debe causar confusión ni implicar patrocinio de Microsoft. Cualquier uso de marcas comerciales o logotipos de terceros está sujeto a las políticas de dichos terceros.

Créditos

La biblioteca DirectXTex es obra de Chuck Walbourn, con contribuciones de Matt Lee, Xin Huang, Craig Peeper y muchos otros ingenieros de Microsoft que desarrollaron la biblioteca de utilidades D3DX a lo largo de los años.

Gracias a Paul Penson por su ayuda con la implementación de MemoryStreamOnBlob .

Gracias a Andrew Farrier y Scott Matloff por su ayuda continua con las revisiones de código.

Gracias a Park DongHa por su contribución de las funciones auxiliares JPEG/PNG.