diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index dcefcc2e..09c36643 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -299,30 +299,4 @@ When reviewing documentation, do the following: ## Release Process -1. Ensure all changes are merged into the `main` branch and that all tests pass. -2. Git pull the local repository to ensure it is up to date with the `main` branch. -3. Run the PowerShell script `build\preparerelease.ps1` which will generate a topic branch for the release, update the version number in `CMakeLists.txt`, the `README.md` file, the release notes in the nuspec files, and create a stub in the `CHANGELOG.md` file for the new release. -4. Edit the `CHANGELOG.md` file to update it with a summary of changes. -5. Submit the topic branch for review and merge into `main` once approved. Allow the GitHub Actions workflows and the Azure DevOps pipelines to complete successfully before proceeding. -6. Run the PowerShell script `build\completerelease.ps1` which will set a tag on the project repo and the test repo, and create a release on GitHub with the release notes from `CHANGELOG.md`. Ensure you have set up GPG signing for your GitHub account so that the tags will be verified. -7. Git pull the local repository to ensure it is up to date with the `main` branch. Be sure to include `--tags`. -8. Push the `main` branch to the MSCodeHub mirror repository. Be sure to include `--tags`. -9. Create a PR on MSCodeHub from the `main` branch to the `release` branch. -10. Merge the PR on MSCodeHub to update the release branch, which will trigger the Azure DevOps pipeline to build signed binaries and the NuGet packages. -11. Run the PowerShell script `build\downloadartifacts.ps1` to download the signed binaries from the Azure DevOps pipeline artifacts. -12. Edit the GitHub release and upload the signed binaries to the release assets. -13. Download the GitHub source .zip archive from the release. Unzip and compare to the local repo to ensure it matches — keep in mind there may be some CR/LF differences. Run minisign on the .zip to generate a signature file, and upload the signature file to the release assets. -14. Validate the NuGet packages with by pushing the NuGet packages to a local Packages Source folder, updating the NuGet packages from that folder, and then build the project. -15. Run the PowerShell script `build\promotenuget.ps1` with the `-Release` parameter to promote the version to the Release view on the project-scoped ADO feed. -16. Run the MSCodeHub pipeline to publish the NuGet packages to nuget.org. The pipeline will automatically push the most recent package promoted to the Release view to nuget.org. -17. Git pull a local repository of VCPKG to `d:\vcpkg` in sync with the `main` branch of the VCPKG repository. -18. Run the PowerShell script `build\updatevcpkg.ps1` to update the DirectXTex port in VCPKG with the new release version. This will edit the files in `ports\directxtex`. -19. Test the VCPKG port using all appropriate triplets and features. -20. Run `.\vcpkg --x-add-version directxtex` to update the VCPKG versioning history. -21. Submit a PR to the VCPKG repository to update the DirectXTex port back to the main GitHub repo. The PR will be reviewed and merged by the VCPKG maintainers. -22. If relevant changes were made to the `texassemble`, `texconv` or `texdiag` tools, update the winget manifests for those tools in the `winget` repository. -- Git pull a local repository to `D:\winget-pkgs` in sync with the `master` branch of the WinGet repository. -- Run the PowerShell script `build\updatewinget.ps1` to update the winget manifests for the tools with the new release version. -- Submit a PR to the `winget` repository to update the manifests for each tool — they must be done as distinct PRs. The PRs will be reviewed and merged by the winget maintainers. - -> When fully completed, be sure to update the GitHub release with links to the matching NuGet packages, the VCPKG port, and the winget manifests for the tools. +The release process is documented in the [release skill](.github/skills/release/SKILL.md). Invoke the `release` skill for step-by-step guidance when performing a release. diff --git a/.github/skills/directxtex-usage/SKILL.md b/.github/skills/directxtex-usage/SKILL.md new file mode 100644 index 00000000..06897baa --- /dev/null +++ b/.github/skills/directxtex-usage/SKILL.md @@ -0,0 +1,336 @@ +--- +name: DirectXTex Usage +description: Guide for integrating and using the DirectXTex texture processing library in new projects. Use this skill when asked about adding DirectXTex to a project, loading/saving textures, format conversion, mipmap generation, block compression, or Direct3D resource creation. +--- + +# DirectXTex Usage Guide + +This skill provides guidance for integrating the DirectXTex texture processing library into a C++ project. + +## When to Use + +Invoke this skill when: + +- Adding DirectXTex as a dependency to a new or existing project. +- Writing code that processes texture data (resizing, format conversion, mipmap generation, DirectX Block Compression, etc.). +- Needing to understand the typical DirectXTex processing pipeline. + +## Overview + +DirectXTex is a texture processing library for Direct3D 11 and Direct3D 12 applications. It provides support for reading and writing DDS files, and performing various texture content processing operations including resizing, format conversion, mipmap generation, block compression, and normal map creation. + +- **Repository**: +- **Documentation**: +- **NuGet Packages**: `directxtex_desktop_win10`, `directxtex_uwp` +- **vcpkg Port**: `directxtex` + +## Integration Methods + +### vcpkg manifest-mode (Recommended) + +In your `vcpkg.json` file, add the following: + +```json +{ + "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json", + "dependencies": [ + "directxtex" + ] +} +``` + +### vcpkg (classic) + +```bash +vcpkg install directxtex +``` + +Features: `dx12` (DirectX 12 API support), `openexr` (OpenEXR support), `tools` (command-line tools). Triplets: `x64-windows`, `x64-linux`, `arm64-windows`, etc. + +For DLL usage (`x64-windows` default triplet), define `DIRECTX_TEX_IMPORT` in your consuming project. For static library usage, use `-static-md` triplet variants. + +CMakeLists.txt: + +```cmake +find_package(directxtex CONFIG REQUIRED) +target_link_libraries(${PROJECT_NAME} PRIVATE Microsoft::DirectXTex) +``` + +### NuGet + +Use `directxtex_desktop_win10` for Win32 desktop applications or `directxtex_uwp` for UWP apps. + +### Project Reference + +Add the appropriate `.vcxproj` from the `DirectXTex/` folder to your solution and add a project reference. Add the `DirectXTex` directory to your Additional Include Directories. + +## Header Include + +```cpp +#include // or — include BEFORE DirectXTex.h +#include + +using namespace DirectX; +``` + +For auxiliary features, include additional headers: + +```cpp +#include // OpenEXR support +#include // libjpeg support (non-WIC) +#include // libpng support (non-WIC) +#include // Xbox tiling extensions +``` + +> DirectXTexJPEG, DirectXTexPNG are typically only used on Linux. + +## Key Concepts + +### ScratchImage + +`ScratchImage` is the primary image container. It owns pixel memory and provides access to individual mip levels, array slices, and volume depth slices. + +```cpp +ScratchImage image; +HRESULT hr = LoadFromDDSFile(L"texture.dds", DDS_FLAGS_NONE, nullptr, image); +if (FAILED(hr)) + // handle error + +const TexMetadata& metadata = image.GetMetadata(); +const Image* img = image.GetImage(0, 0, 0); // mip 0, item 0, slice 0 +``` + +### TexMetadata + +Describes the texture dimensions, format, mip levels, array size, and type (1D, 2D, 3D, cubemap). + +### Blob + +A memory buffer used for serialized output (e.g., saving to memory rather than files). + +### Error Handling + +All processing functions return `HRESULT`. Check with `FAILED()` / `SUCCEEDED()` macros. + +## Common Workflows + +### Loading Textures + +```cpp +// From DDS file +ScratchImage image; +HRESULT hr = LoadFromDDSFile(L"texture.dds", DDS_FLAGS_NONE, nullptr, image); + +// From WIC file (PNG, BMP, JPEG, TIFF, etc.) — Windows only +ScratchImage image; +HRESULT hr = LoadFromWICFile(L"texture.png", WIC_FLAGS_NONE, nullptr, image); + +// From TGA file +ScratchImage image; +HRESULT hr = LoadFromTGAFile(L"texture.tga", TGA_FLAGS_NONE, nullptr, image); + +// From HDR file +ScratchImage image; +HRESULT hr = LoadFromHDRFile(L"texture.hdr", nullptr, image); + +// From memory +ScratchImage image; +HRESULT hr = LoadFromDDSMemory(pData, dataSize, DDS_FLAGS_NONE, nullptr, image); +``` + +### Saving Textures + +```cpp +// Save to DDS file +const Image* img = image.GetImages(); +size_t nimages = image.GetImageCount(); +const TexMetadata& metadata = image.GetMetadata(); +HRESULT hr = SaveToDDSFile(img, nimages, metadata, DDS_FLAGS_NONE, L"output.dds"); + +// Save single image to WIC file (PNG) — Windows only +hr = SaveToWICFile(*image.GetImage(0, 0, 0), WIC_FLAGS_NONE, + GetWICCodec(WIC_CODEC_PNG), L"output.png"); + +// Save to memory blob +Blob blob; +hr = SaveToDDSMemory(img, nimages, metadata, DDS_FLAGS_NONE, blob); +``` + +### Format Conversion + +```cpp +ScratchImage converted; +HRESULT hr = Convert(image.GetImages(), image.GetImageCount(), image.GetMetadata(), + DXGI_FORMAT_R8G8B8A8_UNORM, TEX_FILTER_DEFAULT, TEX_THRESHOLD_DEFAULT, converted); +``` + +### Resizing + +```cpp +ScratchImage resized; +HRESULT hr = Resize(image.GetImages(), image.GetImageCount(), image.GetMetadata(), + 1024, 1024, TEX_FILTER_DEFAULT, resized); +``` + +### Mipmap Generation + +```cpp +ScratchImage mipChain; +HRESULT hr = GenerateMipMaps(image.GetImages(), image.GetImageCount(), image.GetMetadata(), + TEX_FILTER_DEFAULT, 0, mipChain); +// 0 levels = generate full mip chain +``` + +### Block Compression + +```cpp +ScratchImage compressed; +HRESULT hr = Compress(image.GetImages(), image.GetImageCount(), image.GetMetadata(), + DXGI_FORMAT_BC7_UNORM, TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT, compressed); + +// GPU-accelerated BC6H/BC7 compression (Direct3D 11) +ScratchImage compressed; +HRESULT hr = Compress(pDevice, image.GetImages(), image.GetImageCount(), image.GetMetadata(), + DXGI_FORMAT_BC7_UNORM, TEX_COMPRESS_DEFAULT, TEX_ALPHA_WEIGHT_DEFAULT, compressed); +``` + +### Decompression + +```cpp +ScratchImage decompressed; +HRESULT hr = Decompress(image.GetImages(), image.GetImageCount(), image.GetMetadata(), + DXGI_FORMAT_R8G8B8A8_UNORM, decompressed); +``` + +### Normal Map Generation + +```cpp +ScratchImage normalMap; +HRESULT hr = ComputeNormalMap(*image.GetImage(0, 0, 0), + CNMAP_CHANNEL_LUMINANCE, 2.0f, + DXGI_FORMAT_R8G8B8A8_UNORM, normalMap); +``` + +### Premultiplied Alpha + +```cpp +ScratchImage pmAlpha; +HRESULT hr = PremultiplyAlpha(image.GetImages(), image.GetImageCount(), image.GetMetadata(), + TEX_PMALPHA_DEFAULT, pmAlpha); +``` + +### Creating Direct3D 11 Resources + +```cpp +#include +#include + +// Create texture resource +ID3D11Resource* pTexture = nullptr; +HRESULT hr = CreateTexture(pDevice, image.GetImages(), image.GetImageCount(), + image.GetMetadata(), &pTexture); + +// Create shader resource view directly +ID3D11ShaderResourceView* pSRV = nullptr; +hr = CreateShaderResourceView(pDevice, image.GetImages(), image.GetImageCount(), + image.GetMetadata(), &pSRV); +``` + +### Creating Direct3D 12 Resources + +```cpp +#include +#include + +// Create committed resource +ID3D12Resource* pTexture = nullptr; +HRESULT hr = CreateTexture(pDevice, image.GetMetadata(), &pTexture); + +// Prepare upload data for CopyTextureRegion +std::vector subresources; +hr = PrepareUpload(pDevice, image.GetImages(), image.GetImageCount(), + image.GetMetadata(), subresources); +``` + +## Typical Texture Pipeline + +A common offline texture processing pipeline: + +```cpp +// 1. Load source image +ScratchImage source; +HRESULT hr = LoadFromWICFile(L"diffuse.png", WIC_FLAGS_NONE, nullptr, source); +if (FAILED(hr)) return hr; + +// 2. Resize if needed +ScratchImage resized; +if (source.GetMetadata().width != 1024 || source.GetMetadata().height != 1024) +{ + hr = Resize(*source.GetImage(0, 0, 0), 1024, 1024, TEX_FILTER_DEFAULT, resized); + if (FAILED(hr)) return hr; +} +else +{ + resized = std::move(source); +} + +// 3. Generate mipmaps +ScratchImage mipChain; +hr = GenerateMipMaps(*resized.GetImage(0, 0, 0), TEX_FILTER_DEFAULT, 0, mipChain); +if (FAILED(hr)) return hr; + +// 4. Compress to BC7 +ScratchImage compressed; +hr = Compress(mipChain.GetImages(), mipChain.GetImageCount(), mipChain.GetMetadata(), + DXGI_FORMAT_BC7_UNORM, TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT, compressed); +if (FAILED(hr)) return hr; + +// 5. Save as DDS +hr = SaveToDDSFile(compressed.GetImages(), compressed.GetImageCount(), + compressed.GetMetadata(), DDS_FLAGS_NONE, L"diffuse.dds"); +``` + +## Format Utilities + +DirectXTex provides utility functions for querying DXGI format properties: + +```cpp +bool compressed = IsCompressed(DXGI_FORMAT_BC7_UNORM); // true +size_t bpp = BitsPerPixel(DXGI_FORMAT_R8G8B8A8_UNORM); // 32 +bool srgb = IsSRGB(DXGI_FORMAT_R8G8B8A8_UNORM_SRGB); // true + +DXGI_FORMAT srgbFmt = MakeSRGB(DXGI_FORMAT_R8G8B8A8_UNORM); // _SRGB variant +DXGI_FORMAT linearFmt = MakeLinear(DXGI_FORMAT_R8G8B8A8_UNORM_SRGB); // non-SRGB + +size_t rowPitch, slicePitch; +ComputePitch(DXGI_FORMAT_R8G8B8A8_UNORM, 256, 256, rowPitch, slicePitch); +``` + +## Platform Support + +| Platform | DDS | HDR | TGA | WIC | Direct3D 11 | Direct3D 12 | +| --- | --- | --- | --- | --- | --- | --- | +| Windows desktop | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| UWP | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Xbox (GDK) | ✓ | ✓ | ✓ | — | ✓ | ✓ | +| Linux | ✓ | ✓ | ✓ | — | — | — | + +## Command-Line Tools + +DirectXTex includes three CLI tools for texture processing: + +- **texconv** — Convert images to DDS with compression, mipmaps, and resizing +- **texassemble** — Create cubemaps, texture arrays, and volume maps from individual images +- **texdiag** — Inspect and validate DDS files + +Example texconv usage: + +```bash +texconv -f BC7_UNORM -m 0 -y diffuse.png +``` + +## Further Reading + +- [Getting Started](https://github.com/microsoft/DirectXTex/wiki/Getting-Started) +- [DirectXTex Wiki](https://github.com/microsoft/DirectXTex/wiki) +- [API Reference](reference/overview.md) diff --git a/.github/skills/directxtex-usage/reference/overview.md b/.github/skills/directxtex-usage/reference/overview.md new file mode 100644 index 00000000..735e0046 --- /dev/null +++ b/.github/skills/directxtex-usage/reference/overview.md @@ -0,0 +1,304 @@ +# DirectXTex API Reference + +This document provides an overview of the DirectXTex public API. Full function signatures with SAL annotations can be found in `DirectXTex/DirectXTex.h`. + +## Namespace + +All DirectXTex functions and types reside in the `DirectX` namespace. + +## DXGI Format Utilities + +| Function | Description | +| --- | --- | +| `IsValid` | Returns true if fmt is a valid DXGI_FORMAT value | +| `IsCompressed` | Returns true for BC1–BC7 block-compressed formats | +| `IsPacked` | Returns true for packed formats (e.g., R8G8_B8G8) | +| `IsVideo` | Returns true for video-specific formats | +| `IsPlanar` | Returns true for planar formats (e.g., NV12) | +| `IsPalettized` | Returns true for palettized formats | +| `IsDepthStencil` | Returns true for depth/stencil formats | +| `IsSRGB` | Returns true for sRGB formats | +| `IsBGR` | Returns true for BGR-ordered formats | +| `IsTypeless` | Returns true for typeless formats | +| `HasAlpha` | Returns true if the format includes an alpha channel | +| `BitsPerPixel` | Returns bits per pixel for the format | +| `BitsPerColor` | Returns bits per color channel | +| `BytesPerBlock` | Returns bytes per block for compressed formats | +| `FormatDataType` | Returns the data type classification (float, unorm, etc.) | +| `ComputePitch` | Computes row and slice pitch for a given format and dimensions | +| `ComputeScanlines` | Computes number of scanlines including BC padding | +| `CalculateMipLevels` | Calculates valid mip level count for 1D/2D textures | +| `CalculateMipLevels3D` | Calculates valid mip level count for volume textures | +| `MakeSRGB` | Converts format to its sRGB equivalent | +| `MakeLinear` | Converts format to its linear (non-sRGB) equivalent | +| `MakeTypeless` | Converts format to its typeless equivalent | +| `MakeTypelessUNORM` | Converts typeless format to UNORM equivalent | +| `MakeTypelessFLOAT` | Converts typeless format to FLOAT equivalent | + +## Structures + +### TexMetadata + +Describes complete texture resource properties. + +| Field | Type | Description | +| --- | --- | --- | +| `width` | `size_t` | Texture width in pixels | +| `height` | `size_t` | Texture height (1 for 1D textures) | +| `depth` | `size_t` | Texture depth (1 for 1D/2D textures) | +| `arraySize` | `size_t` | Array size (multiple of 6 for cubemaps) | +| `mipLevels` | `size_t` | Number of mip levels | +| `miscFlags` | `uint32_t` | Miscellaneous flags (e.g., `TEX_MISC_TEXTURECUBE`) | +| `miscFlags2` | `uint32_t` | Additional flags (alpha mode encoded here) | +| `format` | `DXGI_FORMAT` | Pixel format | +| `dimension` | `TEX_DIMENSION` | Resource dimension (1D, 2D, 3D) | + +Methods: `ComputeIndex`, `IsCubemap`, `IsPMAlpha`, `SetAlphaMode`, `GetAlphaMode`, `IsVolumemap`, `CalculateSubresource` + +### DDSMetaData + +Contains the original DDS pixel format header information for advanced use cases. + +### Image + +Describes a single 2D image surface within a `ScratchImage`. + +| Field | Type | Description | +| --- | --- | --- | +| `width` | `size_t` | Image width | +| `height` | `size_t` | Image height | +| `format` | `DXGI_FORMAT` | Pixel format | +| `rowPitch` | `size_t` | Bytes per row | +| `slicePitch` | `size_t` | Total bytes for the image | +| `pixels` | `uint8_t*` | Pointer to pixel data | + +### ScratchImage + +RAII container that owns texture pixel data. Move-only (copy deleted). + +| Method | Description | +| --- | --- | +| `Initialize` | Initialize from TexMetadata | +| `Initialize1D` / `Initialize2D` / `Initialize3D` | Initialize for specific dimension | +| `InitializeCube` | Initialize as cubemap | +| `InitializeFromImage` | Initialize from a single Image | +| `InitializeArrayFromImages` | Initialize array from multiple Images | +| `InitializeCubeFromImages` | Initialize cubemap from face Images | +| `Initialize3DFromImages` | Initialize volume from depth-slice Images | +| `Release` | Free all memory | +| `OverrideFormat` | Change format tag without conversion | +| `GetMetadata` | Access TexMetadata | +| `GetImage` | Access specific image in the texture | +| `GetImages` / `GetImageCount` | Access all images | +| `GetPixels` / `GetPixelsSize` | Access raw pixel memory | +| `IsAlphaAllOpaque` | Check if alpha is all opaque | + +### Blob + +16-byte-aligned memory buffer for serialized output. + +| Method | Description | +| --- | --- | +| `Initialize` | Allocate buffer | +| `Release` | Free buffer | +| `GetBufferPointer` | Get mutable pointer | +| `GetConstBufferPointer` | Get const pointer | +| `GetBufferSize` | Get buffer size | +| `Resize` | Reallocate to new size | +| `Trim` | Reduce size without reallocation | + +### Rect + +Simple rectangle for `CopyRectangle` operations: `x`, `y`, `w`, `h`. + +### TileShape + +Describes a tile shape for tiled/reserved resources (D3D11/D3D12 interop). + +## Image I/O Functions + +> See `DirectXTex/DirectXTex.h` for full function signatures with SAL annotations. + +### DDS + +| Function | Description | +| --- | --- | +| `GetMetadataFromDDSFile` | Read metadata from a DDS file | +| `GetMetadataFromDDSMemory` | Read metadata from DDS data in memory | +| `GetMetadataFromDDSFileEx` | Read metadata and pixel format from a DDS file | +| `GetMetadataFromDDSMemoryEx` | Read metadata and pixel format from DDS data in memory | +| `LoadFromDDSFile` | Load a DDS file into a ScratchImage | +| `LoadFromDDSMemory` | Load DDS data from memory into a ScratchImage | +| `LoadFromDDSFileEx` | Load a DDS file with extended pixel format info | +| `LoadFromDDSMemoryEx` | Load DDS data from memory with extended pixel format info | +| `SaveToDDSFile` | Save image(s) to a DDS file | +| `SaveToDDSMemory` | Save image(s) to a DDS blob in memory | + +### HDR (Radiance RGBE) + +| Function | Description | +| --- | --- | +| `GetMetadataFromHDRFile` | Read metadata from an HDR file | +| `GetMetadataFromHDRMemory` | Read metadata from HDR data in memory | +| `LoadFromHDRFile` | Load an HDR file into a ScratchImage | +| `LoadFromHDRMemory` | Load HDR data from memory into a ScratchImage | +| `SaveToHDRFile` | Save a single image to an HDR file | +| `SaveToHDRMemory` | Save a single image to an HDR blob in memory | + +### TGA (Targa) + +| Function | Description | +| --- | --- | +| `GetMetadataFromTGAFile` | Read metadata from a TGA file | +| `GetMetadataFromTGAMemory` | Read metadata from TGA data in memory | +| `LoadFromTGAFile` | Load a TGA file into a ScratchImage | +| `LoadFromTGAMemory` | Load TGA data from memory into a ScratchImage | +| `SaveToTGAFile` | Save a single image to a TGA file | +| `SaveToTGAMemory` | Save a single image to a TGA blob in memory | + +### WIC (Windows only — PNG, BMP, JPEG, TIFF, GIF, etc.) + +| Function | Description | +| --- | --- | +| `GetMetadataFromWICFile` | Read metadata from a WIC-supported file | +| `GetMetadataFromWICMemory` | Read metadata from WIC-supported data in memory | +| `LoadFromWICFile` | Load a WIC-supported file into a ScratchImage | +| `LoadFromWICMemory` | Load WIC-supported data from memory into a ScratchImage | +| `SaveToWICFile` | Save image(s) to a WIC-supported file format | +| `SaveToWICMemory` | Save image(s) to a WIC-supported blob in memory | + +## Texture Processing Functions + +### Resize + +| Function | Description | +| --- | --- | +| `Resize` | Resize image(s) to a new width and height | + +### Convert (Format Conversion) + +| Function | Description | +| --- | --- | +| `Convert` | Convert image(s) to a new pixel format | +| `ConvertEx` | Convert with extended options and progress callback | +| `ConvertToSinglePlane` | Convert planar format to equivalent non-planar format | + +### Mipmap Generation + +| Function | Description | +| --- | --- | +| `GenerateMipMaps` | Generate a full or partial mipmap chain for 1D/2D textures | +| `GenerateMipMaps3D` | Generate a mipmap chain for volume (3D) textures | +| `ScaleMipMapsAlphaForCoverage` | Adjust mip alpha values to preserve coverage | + +### Block Compression + +| Function | Description | +| --- | --- | +| `Compress` | CPU block compression (BC1–BC7) | +| `Compress` (D3D11) | GPU-accelerated BC6H/BC7 compression via DirectCompute | +| `CompressEx` | Compress with extended options and progress callback | +| `CompressEx` (D3D11) | GPU-accelerated compress with extended options | +| `Decompress` | Decompress block-compressed image(s) to a standard format | + +### Flip/Rotate (Windows only) + +| Function | Description | +| --- | --- | +| `FlipRotate` | Flip and/or rotate image(s) | + +### Premultiplied Alpha + +| Function | Description | +| --- | --- | +| `PremultiplyAlpha` | Convert between straight and premultiplied alpha | + +### Normal Map + +| Function | Description | +| --- | --- | +| `ComputeNormalMap` | Generate a normal map from a height map image | + +### Misc Image Operations + +| Function | Description | +| --- | --- | +| `CopyRectangle` | Copy a rectangular region between images | +| `ComputeMSE` | Compute mean-squared error between two images | +| `EvaluateImage` | Iterate over image pixels with a read-only callback | +| `TransformImage` | Transform image pixels with a read/write callback | + +## DDS Helper Functions + +| Function | Description | +| --- | --- | +| `EncodeDDSHeader` | Encode a DDS header from TexMetadata | + +## Tiling Utilities + +| Function | Description | +| --- | --- | +| `ComputeTileShape` | Compute the tile dimensions for a given format and dimension | + +## WIC Utilities (Windows only) + +| Function | Description | +| --- | --- | +| `GetWICCodec` | Get the WIC container format GUID for a codec enum | +| `GetWICFactory` | Get the shared WIC imaging factory | +| `SetWICFactory` | Set a custom WIC imaging factory | + +## Direct3D 11 Interop + +| Function | Description | +| --- | --- | +| `IsSupportedTexture` | Check if a texture format/layout is supported by the device | +| `CreateTexture` | Create a D3D11 texture resource from image data | +| `CreateShaderResourceView` | Create a D3D11 SRV from image data | +| `CreateTextureEx` | Create a D3D11 texture with explicit usage/bind flags | +| `CreateShaderResourceViewEx` | Create a D3D11 SRV with explicit usage/bind flags | +| `CaptureTexture` | Copy a D3D11 texture resource into a ScratchImage | + +## Direct3D 12 Interop + +| Function | Description | +| --- | --- | +| `IsSupportedTexture` | Check if a texture format/layout is supported by the device | +| `CreateTexture` | Create a D3D12 committed resource from metadata | +| `CreateTextureEx` | Create a D3D12 committed resource with explicit resource flags | +| `PrepareUpload` | Prepare subresource data for upload via copy queue | +| `CaptureTexture` | Copy a D3D12 texture resource into a ScratchImage | + +## Flags Enumerations + +| Enum | Purpose | +| --- | --- | +| `CP_FLAGS` | Pitch computation alignment options | +| `DDS_FLAGS` | DDS load/save behavior options | +| `TGA_FLAGS` | TGA load/save options | +| `WIC_FLAGS` | WIC load/save options | +| `TEX_FR_FLAGS` | Flip/rotate operations | +| `TEX_FILTER_FLAGS` | Filtering mode for resize/convert/mipgen | +| `TEX_PMALPHA_FLAGS` | Premultiplied alpha conversion options | +| `TEX_COMPRESS_FLAGS` | Block compression options | +| `CNMAP_FLAGS` | Normal map generation options | +| `CMSE_FLAGS` | Mean-squared error comparison options | +| `CREATETEX_FLAGS` | Direct3D texture creation options | + +## Auxiliary Modules + +### DirectXTexEXR (`Auxiliary/DirectXTexEXR.h`) + +OpenEXR format support via the OpenEXR library. + +### DirectXTexJPEG (`Auxiliary/DirectXTexJPEG.h`) + +JPEG support via libjpeg (cross-platform, does not require WIC). + +### DirectXTexPNG (`Auxiliary/DirectXTexPNG.h`) + +PNG support via libpng (cross-platform, does not require WIC). + +### DirectXTexXbox (`Auxiliary/DirectXTexXbox.h`) + +Xbox-specific tiling/detiling and DDS extensions for Xbox One and Xbox Series X|S. diff --git a/.github/skills/release/SKILL.md b/.github/skills/release/SKILL.md new file mode 100644 index 00000000..ee0f4b85 --- /dev/null +++ b/.github/skills/release/SKILL.md @@ -0,0 +1,83 @@ +--- +name: Release Process +description: Guide for performing the DirectXTex release process. Use this skill when asked to help with releasing a new version, publishing packages, or updating ports. +--- + +# Release Process + +## Prerequisites + +- All changes merged into the `main` branch with all tests passing. +- GPG signing configured for your GitHub account (for verified tags). +- Access to the MSCodeHub mirror repository and Azure DevOps pipelines. +- Local repositories: + - VCPKG at `d:\vcpkg` (synced with `main` branch) + - WinGet at `D:\winget-pkgs` (synced with `master` branch, only if tool updates needed) +- PATs will be needed for scripts that access GitHub and ADO. + + +## Steps + +### Phase 1: Prepare Release + +1. Git pull the local repository to ensure it is up to date with the `main` branch. +2. Run the PowerShell script `build\preparerelease.ps1` which will generate a topic branch for the release, update the version number in `CMakeLists.txt`, the `README.md` file, the release notes in the nuspec files, and create a stub in the `CHANGELOG.md` file for the new release. +3. Edit the `CHANGELOG.md` file to update it with a summary of changes. +4. Submit the topic branch for review and merge into `main` once approved. Allow the GitHub Actions workflows and the Azure DevOps pipelines to complete successfully before proceeding. + +### Phase 2: Tag and Create GitHub Release + +5. Run the PowerShell script `build\completerelease.ps1` which will set a tag on the project repo and the test repo, and create a release on GitHub with the release notes from `CHANGELOG.md`. Ensure you have set up GPG signing for your GitHub account so that the tags will be verified. +6. Git pull the local repository to ensure it is up to date with the `main` branch. Be sure to include `--tags`. + +### Phase 3: MSCodeHub and Signed Binaries + +7. Push the `main` branch to the MSCodeHub mirror repository. Be sure to include `--tags`. +8. Create a PR on MSCodeHub from the `main` branch to the `release` branch. +9. Merge the PR on MSCodeHub to update the release branch, which will trigger the Azure DevOps pipeline to build signed binaries and the NuGet packages. +10. Run the PowerShell script `build\downloadbuild.ps1` to download the signed binaries from the Azure DevOps pipeline artifacts. +11. Edit the GitHub release and upload the signed binaries to the release assets. + +### Phase 4: Source Archive Signing + +12. Download the GitHub source .zip archive from the release. Unzip and compare to the local repo to ensure it matches — keep in mind there may be some CR/LF differences. +13. Run minisign on the .zip to generate a signature file, and upload the signature file to the release assets. + +### Phase 5: NuGet Validation and Publishing + +14. Validate the NuGet packages with by pushing the NuGet packages to a local Packages Source folder, updating the NuGet packages from that folder, and then build the project. +15. Run the PowerShell script `build\promotenuget.ps1 -Version -Release` to promote the version to the Release view on the project-scoped ADO feed. The `-Version` parameter is required and should match the NuGet package version (e.g., `2026.6.2.1`). +16. Run the MSCodeHub pipeline to publish the NuGet packages to nuget.org. The pipeline will automatically push the most recent package promoted to the Release view to nuget.org. + +### Phase 6: VCPKG Port Update + +17. Git pull a local repository of VCPKG to `d:\vcpkg` in sync with the `main` branch of the VCPKG repository. +18. Run the PowerShell script `build\updatevcpkg.ps1` to update the DirectXTex port in VCPKG with the new release version. This will edit the files in `ports\directxtex`. + If the port includes patches, review them to determine if they should be removed or updated for the new release (the `updatevcpkg.ps1` script will warn about this). +19. Test the VCPKG port using the script at `assets/vcpkgdxtex.cmd` (in this skill folder). Copy it to `d:\vcpkg` and run from there after bootstrapping VCPKG. +20. Run `.\vcpkg x-add-version directxtex` to update the VCPKG versioning history. +21. Submit a PR to the VCPKG repository to update the DirectXTex port back to the main GitHub repo. The PR will be reviewed and merged by the VCPKG maintainers. + +### Phase 7: WinGet Manifests (Conditional) + +If relevant changes were made to the `texassemble`, `texconv` or `texdiag` tools: + +22. Git pull a local repository to `D:\winget-pkgs` in sync with the `master` branch of the WinGet repository. +23. Run the PowerShell script `build\updatewinget.ps1` to update the winget manifests for the tools with the new release version. +24. Submit a PR to the `winget` repository to update the manifests for each tool — they must be done as distinct PRs. The PRs will be reviewed and merged by the winget maintainers. + +### Phase 8: Finalize + +When fully completed, be sure to update the GitHub release with links to the matching NuGet packages, the VCPKG port, and the winget manifests for the tools. + +## Key Scripts + +| Script | Purpose | +| --- | --- | +| `build\preparerelease.ps1` | Creates topic branch, updates version numbers and changelog stub | +| `build\completerelease.ps1` | Sets tags, creates GitHub release from changelog | +| `build\downloadbuild.ps1` | Downloads signed binaries from Azure DevOps | +| `build\promotenuget.ps1` | Promotes NuGet package to Release view on ADO feed | +| `build\updatevcpkg.ps1` | Updates DirectXTex VCPKG port files | +| `assets\vcpkgdxtex.cmd` | Tests VCPKG port across all triplets and features | +| `build\updatewinget.ps1` | Updates winget manifests for CLI tools | diff --git a/.github/skills/release/assets/vcpkgdxtex.cmd b/.github/skills/release/assets/vcpkgdxtex.cmd new file mode 100644 index 00000000..9c4ba779 --- /dev/null +++ b/.github/skills/release/assets/vcpkgdxtex.cmd @@ -0,0 +1,174 @@ +@set VCPKG_BINARY_SOURCES=clear +@set VCPKG_ROOT=%cd% +@if %1.==xbox. goto xbox +@if %1.==clang. goto clang +.\vcpkg install directxtex[core]:x86-windows +@if errorlevel 1 goto error +.\vcpkg install directxtex:x86-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:x86-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[dx12]:x86-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[openexr,tools]:x86-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[spectre]:x86-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:x86-windows-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:x86-windows-static-md +@if errorlevel 1 goto error +.\vcpkg install directxtex[core]:x64-windows +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:x64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[dx12]:x64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[openexr,tools]:x64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[spectre]:x64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-windows-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-windows-static-md +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-windows +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:arm64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[spectre]:arm64-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-windows-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-windows-static-md +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64ec-windows +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:arm64ec-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[spectre]:arm64ec-windows --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:x86-uwp +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-uwp +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-uwp +@if errorlevel 1 goto error +@where /Q x86_64-w64-mingw32-g++.exe +@if errorlevel 1 goto skipgcc64 +.\vcpkg install directxtex:x64-mingw-dynamic +@if errorlevel 1 goto error +.\vcpkg install directxtex[dx12]:x64-mingw-dynamic --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:x64-mingw-dynamic --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-mingw-static +@if errorlevel 1 goto error +.\vcpkg install directxtex[dx12]:x64-mingw-static --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:x64-mingw-static --recurse +@if errorlevel 1 goto error +:skipgcc64 +@where /Q i686-w64-mingw32-g++.exe +@if errorlevel 1 goto skipgcc32 +.\vcpkg install directxtex:x86-mingw-static +@if errorlevel 1 goto :error +.\vcpkg install directxtex[dx12]:x86-mingw-static --recurse +@if errorlevel 1 goto :error +.\vcpkg install directxtex[tools]:x86-mingw-static --recurse +@if errorlevel 1 goto :error +.\vcpkg install directxtex:x86-mingw-dynamic +@if errorlevel 1 goto :error +.\vcpkg install directxtex[dx12]:x86-mingw-dynamic --recurse +@if errorlevel 1 goto :error +.\vcpkg install directxtex[tools]:x86-mingw-dynamic --recurse +@if errorlevel 1 goto :error +:skipgcc32 +@if "%GXDKLatest%."=="." goto finish +:xbox +.\vcpkg install directxtex:x64-xbox-scarlett +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-xbox-scarlett-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-xbox-xboxone +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-xbox-xboxone-static +@if errorlevel 1 goto error +@if exist "%VCPKG_ROOT%\installed\x64-windows\include\DirectXTex.h" .\vcpkg remove directxtex:x64-windows +@if errorlevel 1 goto error +.\vcpkg install directxtex[xbox,tools]:x64-windows --recurse +@if errorlevel 1 goto error +@goto finish +:clang +.\vcpkg install directxtex[core]:x64-clangcl-dynamic +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-clangcl-dynamic --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:x64-clangcl-dynamic --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex[dx12]:x64-clangcl-dynamic --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-clangcl-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-clangcl-dynamic +@if errorlevel 1 goto error +.\vcpkg install directxtex[tools]:arm64-clangcl-dynamic --recurse +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-clangcl-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-clangcl-uwp +@if errorlevel 1 goto error +.\vcpkg install directxtex:arm64-clangcl-uwp +@if errorlevel 1 goto error +@if "%GXDKLatest%."=="." goto finish +.\vcpkg install directxtex:x64-clangcl-scarlett +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-clangcl-scarlett-static +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-clangcl-xboxone +@if errorlevel 1 goto error +.\vcpkg install directxtex:x64-clangcl-xboxone-static +@if errorlevel 1 goto error +@if exist "%VCPKG_ROOT%\installed\x64-clangcl-dynamic\include\DirectXTex.h" .\vcpkg remove directxtex:x64-clangcl-dynamic +@if errorlevel 1 goto error +.\vcpkg install directxtex[xbox,tools]:x64-clangcl-dynamic --recurse +@if errorlevel 1 goto error +:finish +@echo SUCCEEDED +@if %1.==xbox. goto eof +@if %1.==clang. goto eof +@echo . +@echo . Run on x64-linux and arm64-linux +@echo . ./vcpkg install directxtex +@echo . ./vcpkg install directxtex[dx12] --recurse +@echo . ./vcpkg install directxtex[openexr] --recurse +@echo . ./vcpkg install directxtex[jpeg] --recurse +@echo . ./vcpkg install directxtex[png] --recurse +@where /Q x86_64-w64-mingw32-g++.exe +@if NOT errorlevel 1 goto gcc64 +@echo . +@echo . Run for MinGW64 +@echo . .\vcpkg install directxtex:x64-mingw-dynamic +@echo . .\vcpkg install directxtex[dx12]:x64-mingw-dynamic --recurse +@echo . .\vcpkg install directxtex[tools]:x64-mingw-dynamic --recurse +@echo . .\vcpkg install directxtex:x64-mingw-static +@echo . .\vcpkg install directxtex[dx12]:x64-mingw-static --recurse +@echo . .\vcpkg install directxtex[tools]:x64-mingw-static --recurse +:gcc64 +@where /Q i686-w64-mingw32-g++.exe +@if NOT errorlevel 1 goto gcc32 +@echo . +@echo . Run for MinGW32 +@echo . .\vcpkg install directxtex:x86-mingw-dynamic +@echo . .\vcpkg install directxtex[dx12]:x86-mingw-dynamic --recurse +@echo . .\vcpkg install directxtex[tools]:x86-mingw-dynamic --recurse +@echo . .\vcpkg install directxtex:x86-mingw-static +@echo . .\vcpkg install directxtex[dx12]:x86-mingw-static --recurse +@echo . .\vcpkg install directxtex[tools]:x86-mingw-static --recurse +:gcc32 +@goto eof +:error +@echo FAILED +:eof diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index df5fbd49..71a82c0d 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -61,7 +61,7 @@ jobs: - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0 - name: Initialize CodeQL - uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v3.29.5 + uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0 with: languages: c-cpp build-mode: manual @@ -75,6 +75,6 @@ jobs: run: cmake --build out\build\x64-Debug - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v3.29.5 + uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0 with: category: "/language:c-cpp" diff --git a/.github/workflows/msvc.yml b/.github/workflows/msvc.yml index 5ba752af..d74c765d 100644 --- a/.github/workflows/msvc.yml +++ b/.github/workflows/msvc.yml @@ -85,6 +85,6 @@ jobs: # Upload SARIF file to GitHub Code Scanning Alerts - name: Upload SARIF to GitHub - uses: github/codeql-action/upload-sarif@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v3.29.5 + uses: github/codeql-action/upload-sarif@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0 with: sarif_file: ${{ steps.run-analysis.outputs.sarif }} diff --git a/.gitignore b/.gitignore index d54f83a4..d374c3ae 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,4 @@ x64 /CMakeUserPresets.json /build/vcpkg_installed /build/*.exe +!**/skills/**