craftablescience::blog

Tutorial: Custom Thumbnails (Almost) Everywhere

Wed, 04 Dec 2024 00:00:00 +0000

Background / Definitions

I work with the Source engine a lot. I recently made a C++ library for working with Source engine textures, and I’m reasonably proud of it. While I was working on it, a friend of mine said they’d like to use it to make thumbnails for these texture files, so they’d be much easier to work with in a file browser. I said “hey that sounds really fun” and proceeded to steal their idea and make it myself (with permission). This is how that went down.

For simplicity, I use the terms “thumbnail creator”, “thumbnail generator”, “thumbnail provider”, and “thumbnailer” interchangeably to mean a program or library that handles generating thumbnails.

Thumbnailer Types

Before getting into the process of making thumbnailers, there are two things you should know. There are two main methods of handling thumbnail generation, both with upsides and downsides.

Run a command (usually calling a custom program) which creates the thumbnail image on disk.
- Pros:
  - Easy to program.
  - Can easily use shell scripts or other scripting languages to generate the thumbnail.
- Cons:
  - Time to generate and display a thumbnail is dependent on how fast your storage medium is.
  - The thumbnail must be read by a separate process to be displayed.
Hook into a library which exposes a function to get the raw thumbnail data.
- Pros:
  - More control is given to the calling process over what to do with the data. Should it be written to disk? Perhaps, but maybe for some file types we don’t want to cache the thumbnail because it can be generated very quickly.
  - Time to generate and display a thumbnail is not dependent on how fast your storage medium is.
- Cons:
  - More difficult to program. The library will likely depend on OS-specific code, and there’s usually some degree of boilerplate that must be added.

Linux thumbnailers use the former method. KDE’s thumbnail plugins, Windows thumbnail generators, and macOS thumbnail plugins use the latter method.

Linux (Generic)

I started here, at the easiest end of the spectrum. Doing some basic research, I found the tumbler service, as well as most Linux file browsers, read thumbnailer entries stored in $PREFIX/share/thumbnailers (where $PREFIX is usually /usr) to figure out how to generate thumbnails. Thumbnail entries are simple key-value files that look very similar to desktop entries. They begin with the text [Thumbnailer Entry], and support three keys.

TryExec: optional, the program to check the existence of before executing the command to create the thumbnail.
Exec: required, the command that will result in the thumbnail’s creation if successful.
MimeType: required, a semicolon-separated and terminated list of MIME types to generate thumbnails for.

The command put in for the Exec key supports certain substitutions.

%u: the URI pointing to the input file.
%i: the path to the input file.
%o: the path to the output file.
%s: the maximum desired size of the thumbnail for either dimension, in pixels. This will probably be a power of two between 128 and 4096, inclusive.
%%: the escaped percent character.

For the MimeType field I needed to create a custom MIME type entry, since VTF files are not part of any universally recognized standard. This would also come in handy for the KDE thumbnailer. The MIME type entry standard can be found here. Mine was very simple and looked like this.

xml vtf-thumbnailer.xml


<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<mime-type type="image/x-vtf">
<comment>Valve Texture Format File</comment>
<acronym>VTF</acronym>
<expanded-acronym>Valve Texture Format</expanded-acronym>
<glob-deleteall/>
<glob pattern="*.vtf"/>
<glob pattern="*.VTF"/>
</mime-type>
</mime-info>

Thus, my complete thumbnailer entry looked like this.

toml vtf-thumbnailer.thumbnailer


[Thumbnailer Entry]
TryExec=/opt/vtf-thumbnailer/vtf-thumbnailer
Exec=/opt/vtf-thumbnailer/vtf-thumbnailer -i %i -o %o -s %s
MimeType=image/x-vtf;

(Yes, I install my software in /opt. No particular reason why, it’s just how I learned to do it.)

The program uses these values to create the thumbnail. Thanks to the FreeDesktop thumbnail specification, we can assume the output image from a given thumbnailer will be an 8-bit PNG. The specification also says you should set some extra metadata in the PNG, but this is only required if you’d like the thumbnails to update when their original files’ contents change. These fields are listed in the aforementioned FreeDesktop specification, and are reproduced here for convenience.

Key	Description	Useful?
`Thumb::URI`	The URI of the original file.	Used to find the original file.
`Thumb::MTime`	The modification time of the original file.	Used to invalidate cache entries when the original file’s modification time exceeds the cache entry.
`Thumb::Size`	The size in bytes of the original file.	Can help in verifying the original file has or hasn’t changed, but mostly pointless.
`Thumb::Mimetype`	The file MIME type.	Mostly pointless.
`Description`	A description of the thumbnail for accessibility purposes.	Unknown how you’d generate this automatically.
`Software`	The name of the thumbnailer that generated the thumbnail.	Pointless.

I ignored this metadata step because I was using stb_image_write to save the PNG, and it doesn’t support setting PNG metadata fields. It didn’t really impact the thumbnailer’s functionality, so I didn’t want to go to the extra trouble.

Three files are written when installing this application. No further installation steps are required beyond writing these files, although a reboot might be necessary to get everything working.

/opt/vtf-thumbnailer/vtf-thumbnailer
/usr/share/mime/packages/vtf-thumbnailer.xml
/usr/share/thumbnailers/vtf-thumbnailer.thumbnailer

Linux’s thumbnailer system is exceedingly simple and very pleasant to work with in general, even if it is a bit slow.

Linux (KDE)

As I finished up work on the thumbnailer, I noticed it was not working in Dolphin. I installed Thunar, observed it working there (which was cool), and then realized Dolphin (or really KDE in general) has a completely different framework for serving thumbnails. This is where things start to get painful.

Dolphin uses KDE-specific plugins, which in turn depend on Qt. This is the basic C++ boilerplate, extracted from the KDE developers’ sample thumbnailer plugin repository.

C++ kde.h


#include <KIO/ThumbnailCreator>
#include <QImage>
class VTFThumbCreator : public KIO::ThumbnailCreator {
public:
using ThumbnailCreator::ThumbnailCreator;
KIO::ThumbnailResult create(const KIO::ThumbnailRequest& request) override;
};

C++ kde.cpp


#include "kde.h"
#include <KPluginFactory>
K_PLUGIN_CLASS_WITH_JSON(VTFThumbCreator, "plugin.json")
KIO::ThumbnailResult VTFThumbCreator::create(const KIO::ThumbnailRequest& request) {
// return KIO::ThumbnailResult::pass(image) with image being a valid QImage
// instance on success
return KIO::ThumbnailResult::fail();
}
#include <kde.moc>

All KDE library plugins have a plugin.json file which gets packed into the binary. In this case it holds important metadata such as whether to cache generated thumbnails, MIME types to generate thumbnails for, and the plugin name.

json plugin.json


{
"CacheThumbnail": false,
"KPlugin": {
"MimeTypes": ["image/x-vtf"],
"Name": "Valve Texture Format Files (VTF Thumbnailer)"
},
"MimeType": "image/x-vtf;"
}

The plugin name will be read by Dolphin and appear as the name of the entry in the previews settings. (And by the way, new plugins must be manually enabled there. If your plugin doesn’t work, make sure it’s both showing up in this menu and that it’s enabled.)

Two more files are necessary for thumbnailer plugins, the XML metadata file and the desktop entry. The metadata file is meant for something like a storefront, where it shows the author, version, description of the plugin, and so on.

xml info.craftablescience.vtf-thumbnailer.metainfo.xml


<?xml version="1.0" encoding="utf-8"?>
<component type="addon">
<id>info.craftablescience.vtf-thumbnailer</id>
<metadata_license>MIT</metadata_license>
<project_license>MIT</project_license>
<extends>org.kde.dolphin.desktop</extends>
<extends>org.kde.konqueror.desktop</extends>
<extends>org.kde.krusader.desktop</extends>
<extends>org.kde.gwenview.desktop</extends>
<name>VTF Thumbnailer</name>
<summary>Valve Texture Format thumbnail generator</summary>
<description>
<p>This plugin allow KDE software to display thumbnails for Valve Texture Format files.</p>
</description>
<url type="homepage">https://github.com/craftablescience/vtf-thumbnailer</url>
<url type="bugtracker">https://github.com/craftablescience/vtf-thumbnailer/issues</url>
<project_group>craftablescience</project_group>
<categories>
<category>Graphics</category>
</categories>
<icon type="stock">application-postscript</icon>
</component>

The desktop entry is used to identify the plugin as a thumbnailer. One important thing to note is when ThumbnailerVersion is incremented after an update, all cached thumbnails created with this thumbnailer will be regenerated if caching is enabled. (Yes, most of these keys are duplicated from the plugin JSON. I don’t exactly know why this file needs to exist.)

toml vtf-thumbnailer.desktop


[Desktop Entry]
Type=Service
Name=Valve Texture Format Files (VTF Thumbnailer)
X-KDE-ServiceTypes=ThumbCreator
MimeType=image/x-vtf;
X-KDE-Library=vtf-thumbnailer
CacheThumbnail=false
ThumbnailerVersion=1

Possibly the most important file that is needed is the CMake buildscript. CMake is essentially required here, as you need to use the KDE CMake utilities to get the correct installation paths for the various files, find/link to KDE Framework libraries, and create the plugin target. Unfortunately it’s a lot of CMake. As with pretty much everything else, I copied most of it from other thumbnailers, making modifications where necessary to allow it to compile for both KDE v5 and v6 depending on the given value of QT_MAJOR_VERSION.

cmake CMakeLists.txt


set(QT_MIN_VERSION "5.15.2")
set(KF_MIN_VERSION "5.92.0")
set(KDE_COMPILERSETTINGS_LEVEL "5.82")
find_package(ECM ${KF_MIN_VERSION} REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(ECMOptionalAddSubdirectory)
include(KDEInstallDirs${QT_MAJOR_VERSION})
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(FeatureSummary)
include(ECMDeprecationSettings)
find_package(Qt${QT_MAJOR_VERSION} ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS Gui)
find_package(KF${QT_MAJOR_VERSION} ${KF_MIN_VERSION} REQUIRED COMPONENTS KIO)
# Plugin
ecm_set_disabled_deprecation_versions(QT 5.15.2 KF 5.100.0)
set(BUILD_SHARED_LIBS ON)
kcoreaddons_add_plugin(vtf-thumbnailer INSTALL_NAMESPACE "kf${QT_MAJOR_VERSION}/vtf-thumbnailer")
target_sources(vtf-thumbnailer PRIVATE
"${CMAKE_CURRENT_SOURCE_DIR}/src/common.cpp"
"${CMAKE_CURRENT_SOURCE_DIR}/src/common.h"
"${CMAKE_CURRENT_SOURCE_DIR}/src/kde.cpp"
"${CMAKE_CURRENT_SOURCE_DIR}/src/kde.h")
target_link_libraries(vtf-thumbnailer PUBLIC
KF${QT_MAJOR_VERSION}::KIOGui
Qt::Gui)
install(TARGETS vtf-thumbnailer
DESTINATION ${KDE_INSTALL_PLUGINDIR})
# Desktop
if(QT_MAJOR_VERSION STREQUAL "6")
set(KDE_INSTALL_KSERVICESDIR "${KDE_INSTALL_DATADIR}/kio")
endif()
install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/kde/vtf-thumbnailer.desktop"
DESTINATION ${KDE_INSTALL_KSERVICESDIR})
# Metadata
install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/kde/info.craftablescience.vtf-thumbnailer.metainfo.xml"
DESTINATION ${KDE_INSTALL_METAINFODIR})
# MIME type info
install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/linux/vtf-thumbnailer.xml"
DESTINATION ${KDE_INSTALL_MIMEDIR}
RENAME "vtf-thumbnailer-kde${QT_MAJOR_VERSION}.xml")

The version of Qt that you compile against matters. If you want your thumbnails to work on KDE Plasma v5, compile against Qt v5. Similarly, for KDE Plasma v6 compile against Qt v6. Qt guarantees compatibility for basic objects like QImage for the entire duration of major versions, so use earlier minor versions of Qt to maximize compatibility. It’s expected that you will ship multiple versions of your thumbnailer built for different major KDE versions (or simply target the latest version and call it a day, but keep in mind as of 2024 Debian still hasn’t updated to KDE v6). Unfortunately, I couldn’t figure out how to compile the plugin for KDE v6 in GitHub Actions, so I only created a release for KDE v5.

Finally, to actually compile this code you need some packages installed. On Debian-based distros the packages are called extra-cmake-modules and libkf5kio-dev, accessible through apt. This took me far longer than I’d like to admit to figure out, as most of the official thumbnailers don’t specify what packages they need to build. I found a listing of KDE’s framework packages on a forum post and slowly pared it down until these two were left.

Five files are written when installing this plugin. For KDE v5, the paths look like this. The computer may need a reboot after installation. I haven’t yet figured out if that’s completely necessary, but it doesn’t hurt.

/usr/lib/plugins/vtf-thumbnailer.so
/usr/lib/plugins/kf5/vtf-thumbnailer/vtf-thumbnailer.so (I still have not figured out why the library gets installed to two separate locations!)
/usr/share/mime/packages/vtf-thumbnailer-kde5.xml
/usr/share/metainfo/info.craftablescience.vtf-thumbnailer.metainfo.xml
/usr/share/kservices5/vtf-thumbnailer.desktop

Windows (Vista onward)

Hell. It’s hell here. After finishing the KDE thumbnail plugin it took about 18 hours more work to figure out the Windows thumbnail provider, and that’s while referencing several examples. Maybe I’m stupid, but I prefer to think Windows is a pile of convoluted garbage that’s been left in the sun too long. I made small tweaks and changes to this code for ages, and the reason it wasn’t working, for presumably several hours, was that I wasn’t exporting all the necessary symbols. But the thing is, some symbols here cannot be exported from C++ with a __declspec declaration, because it would be redefining symbols from some random Windows header. Making a .def file to control symbol visibility is required.

Anyway, Windows is interesting. The thumbnail provider returns an HBITMAP, very much like the KDE plugin’s QImage but infinitely worse. Essentially it’s the same style of code as the KDE plugin but with worse types and infinitely more boilerplate. The metadata files are eschewed for the registry (of course), so registering the thumbnail provider is fairly trivial at least. This is what the code ended up looking like.

C++ Windows Thumbnail Provider BS - Includes


#include <cstddef>
#include <vector>
#define WIN32_LEAN_AND_MEAN
#include <Windows.h>
#include <initguid.h>
#include <ShlObj_core.h>
#include <Shlwapi.h>
#include <strsafe.h>
#include <thumbcache.h>
#include <wrl.h>
#define VTF_THUMBNAILER_CLSID_STR L"{8b206795-0606-40ca-9eac-1d049c7ff3be}"
DEFINE_GUID(VTF_THUMBNAILER_CLSID, 0x8b206795, 0x0606, 0x40ca, 0x9e, 0xac, 0x1d, 0x04, 0x9c, 0x7f, 0xf3, 0xbe);
#define GLOBAL(ret) extern "C" [[maybe_unused]] ret __stdcall

To start, we set up the GUID for the thumbnail provider. I used an online generator, since it has to be unique. Next comes the thumbnail provider class.

C++ Windows Thumbnail Provider BS - Thumbnail Provider


class VTFThumbnailProvider : public IThumbnailProvider, public IInitializeWithStream {
public:
VTFThumbnailProvider()
: refCount(1)
, stream(nullptr) {}
~VTFThumbnailProvider() {
if (this->stream) {
this->stream->Release();
this->stream = nullptr;
}
}
STDMETHOD(QueryInterface)(REFIID riid, void** ppv) override {
static const QITAB qit[] = {
QITABENT(VTFThumbnailProvider, IThumbnailProvider),
QITABENT(VTFThumbnailProvider, IInitializeWithStream),
{nullptr},
};
return QISearch(this, qit, riid, ppv);
}
STDMETHOD_(ULONG, AddRef)() override {
return InterlockedIncrement(&this->refCount);
}
STDMETHOD_(ULONG, Release)() override {
const ULONG rc = InterlockedDecrement(&this->refCount);
if (rc == 0) {
delete this;
return 0;
}
return rc;
}
STDMETHOD(Initialize)(IStream* stream_, DWORD) override {
if (!stream_) {
return E_POINTER;
}
this->stream = stream_;
this->stream->AddRef();
return S_OK;
}
STDMETHOD(GetThumbnail)(UINT cx, HBITMAP* phbmp, WTS_ALPHATYPE* pdwAlpha) override {
if (!phbmp || !pdwAlpha) {
return E_POINTER;
}
if (!this->stream) {
return E_UNEXPECTED;
}
STATSTG stat;
HRESULT hr = this->stream->Stat(&stat, STATFLAG_NONAME);
if (FAILED(hr)) {
return hr;
}
ULONG bytesRead = 0;
std::vector<std::byte> data(stat.cbSize.QuadPart);
hr = this->stream->Read(data.data(), static_cast<ULONG>(stat.cbSize.QuadPart), &bytesRead);
if (FAILED(hr) || bytesRead != stat.cbSize.QuadPart) {
return E_FAIL;
}
// The file's data has now been read to the data vector, process it
// Return E_UNEXPECTED if the file is broken
// Past this point data is now storing BGRA8888 (yes, BGRA8888)
// thumbnail image data
BITMAPINFO bmi = {};
bmi.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
bmi.bmiHeader.biWidth = static_cast<LONG>(width);
bmi.bmiHeader.biHeight = -static_cast<LONG>(height);
bmi.bmiHeader.biPlanes = 1;
bmi.bmiHeader.biBitCount = 32;
bmi.bmiHeader.biCompression = BI_RGB;
void* pBits = nullptr;
HDC hdc = GetDC(nullptr);
HBITMAP hBitmap = CreateDIBSection(hdc, &bmi, DIB_RGB_COLORS, &pBits, nullptr, 0);
ReleaseDC(nullptr, hdc);
if (!hBitmap) {
return E_OUTOFMEMORY;
}
std::memcpy(pBits, data.data(), data.size());
*phbmp = hBitmap;
*pdwAlpha = WTSAT_ARGB;
return S_OK;
}
private:
ULONG refCount;
IStream* stream;
};
GLOBAL(HRESULT) VTFThumbnailProvider_CreateInstance(REFIID riid, void** ppv) {
auto* pNew = new(std::nothrow) VTFThumbnailProvider;
HRESULT hr = pNew ? S_OK : E_OUTOFMEMORY;
if (SUCCEEDED(hr)) {
hr = pNew->QueryInterface(riid, ppv);
pNew->Release();
}
return hr;
}
typedef HRESULT(*PFNCREATEINSTANCE)(REFIID, void**);
struct CLASS_OBJECT_INIT {
const CLSID* pClsid;
PFNCREATEINSTANCE pfnCreate;
};
const CLASS_OBJECT_INIT c_rgClassObjectInit[] = {{&VTF_THUMBNAILER_CLSID, VTFThumbnailProvider_CreateInstance}};

The boilerplate isn’t nasty yet, but working with HBITMAP is frustrating. For some reason it wants to read the pixel order in reverse, so BGRA8888 gets turned into ARGB8888. There are a few formats the bitmap can store pixel data in, but for the sake of simplicity I used BGRA8888 everywhere, even for opaque textures. There’s not too much interesting going on here so let’s move on to the factory.

C++ Windows Thumbnail Provider BS - Thumbnail Provider Factory


HINSTANCE g_hInst = nullptr;
ULONG g_cRefModule = 0;
GLOBAL(BOOL) DllMain(HINSTANCE hInstance, DWORD dwReason, void*) {
if (dwReason == DLL_PROCESS_ATTACH) {
g_hInst = hInstance;
DisableThreadLibraryCalls(hInstance);
}
return TRUE;
}
GLOBAL(void) DllAddRef() {
InterlockedIncrement(&g_cRefModule);
}
GLOBAL(void) DllRelease() {
InterlockedDecrement(&g_cRefModule);
}
GLOBAL(HRESULT) DllCanUnloadNow() {
return !g_cRefModule ? S_OK : S_FALSE;
}
class VTFThumbnailProviderFactory : public IClassFactory {
public:
static HRESULT CreateInstance(REFCLSID clsid, const CLASS_OBJECT_INIT* pClassObjectInits, size_t cClassObjectInits, REFIID riid, void** ppv) {
*ppv = nullptr;
HRESULT hr = CLASS_E_CLASSNOTAVAILABLE;
for (size_t i = 0; i < cClassObjectInits; i++) {
if (clsid == *pClassObjectInits[i].pClsid) {
IClassFactory *pClassFactory = new(std::nothrow) VTFThumbnailProviderFactory(pClassObjectInits[i].pfnCreate);
hr = pClassFactory ? S_OK : E_OUTOFMEMORY;
if (SUCCEEDED(hr)) {
hr = pClassFactory->QueryInterface(riid, ppv);
pClassFactory->Release();
}
break;
}
}
return hr;
}
explicit VTFThumbnailProviderFactory(PFNCREATEINSTANCE pfnCreate_)
: refCount(1)
, pfnCreate(pfnCreate_) {
::DllAddRef();
}
IFACEMETHODIMP QueryInterface(REFIID riid, void** ppv) override {
static const QITAB qit[] = {
QITABENT(VTFThumbnailProviderFactory, IClassFactory),
{nullptr},
};
return QISearch(this, qit, riid, ppv);
}
IFACEMETHODIMP_(ULONG) AddRef() override {
return InterlockedIncrement(&this->refCount);
}
IFACEMETHODIMP_(ULONG) Release() override {
const ULONG rc = InterlockedDecrement(&this->refCount);
if (!rc) {
delete this;
}
return rc;
}
IFACEMETHODIMP CreateInstance(IUnknown* pUnkOuter, REFIID riid, void** ppv) override {
return pUnkOuter ? CLASS_E_NOAGGREGATION : this->pfnCreate(riid, ppv);
}
IFACEMETHODIMP LockServer(BOOL fLock) override {
if (fLock) {
::DllAddRef();
} else {
::DllRelease();
}
return S_OK;
}
private:
~VTFThumbnailProviderFactory() {
::DllRelease();
}
ULONG refCount;
PFNCREATEINSTANCE pfnCreate;
};
GLOBAL(HRESULT) DllGetClassObject(REFCLSID clsid, REFIID riid, void** ppv) {
return VTFThumbnailProviderFactory::CreateInstance(clsid, c_rgClassObjectInit, ARRAYSIZE(c_rgClassObjectInit), riid, ppv);
}

All of that code is boilerplate to create an instance of the thumbnail provider. The following code is more interesting.

C++ Windows Thumbnail Provider BS - Thumbnail Provider Registry


namespace {
HRESULT SetHKCRRegistryKey(LPCWSTR subKey, LPCWSTR valueName, LPCWSTR data) {
HKEY hKey;
LONG result = RegCreateKeyExW(HKEY_CLASSES_ROOT, subKey, 0, nullptr, REG_OPTION_NON_VOLATILE, KEY_WRITE, nullptr, &hKey, nullptr);
if (result != ERROR_SUCCESS) {
return HRESULT_FROM_WIN32(result);
}
result = RegSetValueExW(hKey, valueName, 0, REG_SZ, (const BYTE*) data, (lstrlenW(data) + 1) * sizeof(WCHAR));
RegCloseKey(hKey);
return HRESULT_FROM_WIN32(result);
}
HRESULT DeleteHKCRRegistryKey(LPCWSTR subKey) {
LONG result = SHDeleteKeyW(HKEY_CLASSES_ROOT, subKey);
return HRESULT_FROM_WIN32(result == ERROR_FILE_NOT_FOUND ? ERROR_SUCCESS : result);
}
} // namespace
GLOBAL(HRESULT) DllNotifyShell() {
SHChangeNotify(SHCNE_ASSOCCHANGED, SHCNF_IDLIST, nullptr, nullptr);
return S_OK;
}
GLOBAL(HRESULT) DllRegisterServer() {
wchar_t modulePath[MAX_PATH];
if (!GetModuleFileNameW(g_hInst, modulePath, MAX_PATH)) {
return HRESULT_FROM_WIN32(GetLastError());
}
HRESULT hr;
hr = ::SetHKCRRegistryKey(L"CLSID\\" VTF_THUMBNAILER_CLSID_STR, nullptr, L"Valve Texture Format Files (VTF Thumbnailer)");
if (FAILED(hr)) {
return hr;
}
hr = ::SetHKCRRegistryKey(L"CLSID\\" VTF_THUMBNAILER_CLSID_STR "\\InProcServer32", nullptr, modulePath);
if (FAILED(hr)) {
return hr;
}
hr = ::SetHKCRRegistryKey(L"CLSID\\" VTF_THUMBNAILER_CLSID_STR "\\InProcServer32", L"ThreadingModel", L"Apartment");
if (FAILED(hr)) {
return hr;
}
hr = ::SetHKCRRegistryKey(L".vtf\\ShellEx\\{e357fccd-a995-4576-b01f-234630154e96}", nullptr, VTF_THUMBNAILER_CLSID_STR);
if (SUCCEEDED(hr)) {
::DllNotifyShell();
}
return hr;
}
GLOBAL(HRESULT) DllUnregisterServer() {
HRESULT hr;
hr = ::DeleteHKCRRegistryKey(L"CLSID\\" VTF_THUMBNAILER_CLSID_STR);
if (FAILED(hr)) {
return hr;
}
return ::DeleteHKCRRegistryKey(L".vtf\\ShellEx\\{e357fccd-a995-4576-b01f-234630154e96}");
}

The DllRegisterServer and DllUnregisterServer functions are called in the installer after the files are copied into place through regsvr32.exe. Passing a path to a DLL to this program will call the DllRegisterServer function in the DLL, which in this case modifies the necessary registry values, lets the file browser know there’s a new thumbnail provider, and exits. Running the same command with the /u flag will call the DllUnregisterServer function in the DLL instead.

As for the specific registry keys, each one resides under HKEY_CLASSES_ROOT. The CLSID\<GUID> value is the thumbnail provider name. The value for CLSID\<GUID>\InProcServer32 is the path to the DLL. The value for CLSID\<GUID>\InProcServer32\ThreadingModel should always be Apartment according to the scant Windows docs on thumbnail providers and every example of one I’ve found. Finally, the value for <file extension>\ShellEx\{e357fccd-a995-4576-b01f-234630154e96} (yes, you need that exact GUID) should be your own thumbnail provider’s GUID. These are all Windows needs to find the DLL, load it correctly, and use it on the files you want thumbnails for.

Oh right and here’s the stupid .def file, because the Windows API is just the worst.

def Windows Thumbnail Provider BS - Exports


LIBRARY "vtf-thumbnailer"
EXPORTS
VTFThumbnailProvider_CreateInstance PRIVATE
DllMain PRIVATE
DllAddRef PRIVATE
DllRelease PRIVATE
DllCanUnloadNow PRIVATE
DllGetClassObject PRIVATE
DllNotifyShell PRIVATE
DllRegisterServer PRIVATE
DllUnregisterServer PRIVATE

One DLL is written when installing this application. It should start working immediately without rebooting.

C:\Program Files\vtf-thumbnailer\vtf-thumbnailer.dll

Wrap-Up

At this point I was tired of thumbnailers. I packaged the product and shipped a release, built from the code hosted on this GitHub repository, and haven’t looked back until now. I hope this post helps and/or inspires you to make a thumbnailer of your own, it’s really not that difficult if you have a decent reference and quite rewarding in the end!

Format Deep Dive: VTF (Valve Texture Format)

Tue, 26 Nov 2024 00:00:00 +0000

Background / Definitions

At this point I’m going to assume you are a smart cookie and know what textures are, and why engines need to use custom file formats to store them.

(tl;dr it’s more efficient than loading more accessible formats like PNG, some types of image data cannot be stored in accessible formats like PNG, engines frequently need to assign textures metadata which cannot be done in most accessible formats like PNG)

From this point forward, when I say “image”, “image data”, or “texture data” I’m referring to a two-dimensional array of pixels, and not a file like PNG or VTF.

Finally, I’d like to note that I have no experience with the VTF format for console versions of Source, so this post will strictly focus on the VTF formats found on PC. Console VTFs seem to be very similar, and I might make a separate blog post about them in the future when I have more experience working with them.

Anyway now that that’s out of the way, let’s get into this format.

DDS

Since the first iteration of VTF is based on the DDS file format, let’s go over that first, and then we can see what Valve took inspiration from. Skip past this section if you already know what DDS looks like or don’t particularly care. The DDS header specification looks like this:

C++ DDS Header


struct DDS_Header {
uint32_t signature;
uint32_t headerSize;
uint32_t flags;
uint32_t height;
uint32_t width;
uint32_t pitchOrLinearSize;
uint32_t depth;
uint32_t mipMapCount;
uint32_t _unused0[11];
uint32_t format;
uint32_t caps1;
uint32_t caps2;
uint32_t _unused1[3];
};

DDS files are fairly straightforward when storing basic textures.

signature is always the fourCC code "DDS\0".
headerSize is always 124 bytes.
flags is poorly named, essentially stores a flag for every field of the header with valid data.
height and width store the dimensions of the base image (the first mip level).
pitchOrLinearSize stores the pitch (number of bytes per scan line) in uncompressed textures, or the size in bytes of the first mip level in compressed textures.
depth stores the size of the image in the third dimension (number of layers of a volume texture), if the texture is not a volume texture it may not be set to a valid value.
mipMapCount is self-explanatory, the number of mipmaps stored in the file. Mipmaps are images shrunken by a power of two from the image that came before it.
format is the format of the image data stored in the file.
caps1 and caps2 together define the type of the stored texture (volume texture? cubemap texture?).

Immediately following this header is the image data. The entire file looks something like this image.

VTF

DDS is a nice generic format, but its generic-ness made it unsuited for Valve’s purposes. Valve needs to store several things in their textures that the stock DDS header doesn’t make room for, e.g. a reflectivity vector for faster radiosity calculations.

Early VTF (v7.0-7.2)

VTF may have gone through several internal revisions before the first format we know of publicly, since the major version (yes, major, there are two version integers) has always been set to 7. The minor version is what gets updated when the format changes, and it starts at 0. This is what the first public iteration of VTF’s header looks like.

C++ VTF Header


#pragma pack(push, 16)
struct VTF_Header_70 {
uint32_t signature;
uint32_t majorVersion;
uint32_t minorVersion;
uint32_t headerSize;
uint16_t width;
uint16_t height;
uint32_t flags;
uint16_t frameCount;
uint16_t startFrame;
uint32_t _padding0;
float reflectivity[3];
uint32_t _padding1;
float bumpMapScale;
uint32_t format;
uint8_t mipCount;
uint32_t thumbnailFormat;
uint8_t thumbnailWidth;
uint8_t thumbnailHeight;
};
// Bitwise identical
struct VTF_Header_71 : public VTF_Header_70 {};
#pragma pack(pop)

It doesn’t take a genius to figure out Valve copied Microsoft’s homework. Some of the fields are reordered, but in general the contents of the header flow the same direction. Note that this struct is 16-byte aligned, which is why the reflectivity vector has that weird padding around it.

signature is always the fourCC code "VTF\0".
majorVersion is always 7.
minorVersion ranges from 0 to 6.
headerSize is the same as the DDS headerSize, except this header is smaller since it doesn’t have tons of reserved space.
width and height is the same as in DDS, the width and height of the base mip.
flags is actually different than DDS, and is more what you’d expect from a field named flags. It stores flags. See Appendix A for more information on supported flags.
frameCount is the number of “frames”, and startFrame is the first frame in the animation sequence. Again, more on this later!
reflectivity stores the overall reflectivity of the texture, to be used in radiosity calculations. Valve’s method of calculating it is apparently adding all the pixels’ RGB values together, then dividing by the number of pixels. The reflectivity is stored in RGB order.
bumpMapScale controls the intensity of the bump map, if this texture is a bump map. It can be ignored otherwise.
format is the same as in DDS, the format of the image data stored in the file. See Appendix B for more information on supported format types.
mipCount is renamed from mipMapCount in DDS.
thumbnailFormat, thumbnailWidth, and thumbnailHeight are for the VTF thumbnail. More on this later.

Thumbnail data is stored immediately after the header, followed by the image data.

The thumbnail is a low-resolution copy of the base image, which the engine uses in a couple places when it needs to know general information about the brightness of the texture. It needs to know this information in 2D space, so using the reflectivity vector doesn’t work. The thumbnail format should always be treated as DXT1 even if the format field is different, because there are a few official VTFs that have the wrong format in this field, and every VTF creation tool will create the thumbnail with the DXT1 format. For VTFs created using Valve’s own tooling, the size of the thumbnail is always observed to be 16x16, as long as the image is square. If the image is not square, the thumbnail size will be proportional to the image dimensions, with the largest dimension being 16 (so if the image is 2048x1024, the thumbnail will be 16x8). This behavior is not a hard requirement, and thumbnails that have a different aspect ratio from their source image will still work. Custom sized thumbnails should also work, but there’s no need to go higher, or deviate from what Valve’s official tooling produces.

The base image is used to calculate both the thumbnail and the reflectivity vector.

The flags field controls several things, although it’s also used by vtex, Valve’s texture compiler, to store data about the VTF while it’s being created. Some flags only have meaning in vtex, and some flags only have meaning in the engine. The list of flags seems to change slightly every VTF version, but one important flag is the cubemap flag (2^14). When this flag is enabled, the VTF has either 6 or 7 faces, the first 6 forming a cubemap and the 7th either being garbage data or a spheremap when present. When the cubemap flag is present VTF v7.0 has 6 faces, while v7.1 has 7 faces. Unfortunately, Valve has broken their own rules in regards to the presence of the spheremap in official VTFs in the past, so the only way to know for sure if the spheremap is or isn’t present is to check the size of the VTF’s image data. Fortunately, if the VTF is outside the version range v7.1-7.4 (inclusive), we know for sure the spheremap cannot exist.

The frameCount field controls the number of frames the VTF stores. Frames are used for animated textures, and the frame currently rendered by the game is controlled by the material using the texture. The startFrame is the default value for the current frame (not very complicated).

VTF v7.0-7.1 can’t store volumetric textures, despite the fact that DDS can. They might not have cared to implement support here, since volumetric textures aren’t used anywhere in Valve-published Source engine games (or really anywhere else as far as I can tell). VTF v7.2 adds support for volumetric textures (the only change to the format). At this point in the timeline we’re post-Half-Life 2 release, so they might have been doing internal experiments that would necessitate this change.

C++ VTF Header with Depth


#pragma pack(push, 16)
// All the fields from v7.1 verbatim, plus...
struct VTF_Header_72 : public VTF_Header_71 {
uint16_t depth;
};
#pragma pack(pop)

Now that volumetric textures are in play, we can properly visualize how image data is ordered.

"mipmaps" // 0 to mipCount
{
 "frames" // 0 to frameCount
 {
 "faces" // 0 to number of faces
 { // (either 1, 6, or 7)
 "slices" // 0 to depth
 {
 image data
 }
 }
 }
}

One interesting thing to note is that mipmaps are stored in reverse compared to DDS, going smallest to largest. I don’t know for sure, but my theory is they made this change so less of the file would need to be loaded when loading smaller mip levels from disk. I also don’t think the order would matter too much these days.

Another important consideration is that 3D cubemap textures (cubemaps with a nonzero value for depth) are technically possible to create, but are treated as invalid by the engine. Thus, the face count and the image depth cannot be greater than 1 simultaneously.

Modern VTF (v7.3-7.5)

VTF v7.3 is where Valve starts to pull away from copying DDS, and attempt to make it a nicer container for more kinds of texture metadata by introducing the resource system.

C++ VTF Header with Resources


#pragma pack(push, 16)
// All the fields from v7.2 verbatim, plus...
struct VTF_Header_73 : public VTF_Header_72 {
uint8_t _padding1[3];
uint32_t resourceCount;
uint8_t _padding2[8];
};
// Bitwise identical
struct VTF_Header_74 : public VTF_Header_73 {};
// Bitwise identical
struct VTF_Header_75 : public VTF_Header_74 {};
#pragma pack(pop)
struct VTF_Resource {
uint8_t type[3];
uint8_t flags;
uint32_t data;
};

Resources are stored after the VTF header in the form of the given struct. Each resource entry counts toward the overall headerSize as well. The type is a three character code used to identify the resource. There is currently only one resource flag (2^2), controlling the location of the resource’s data. If this flag is not present, the resource data field holds an absolute offset to the data in the VTF file. If the flag is present, the resource data field holds the resource’s data. This is more efficient for resources that only need to store four bytes of data or less. On non-console platforms the maximum amount of resources in a VTF is 32, but there quite literally are not enough resource types to ever hit this maximum.

The only required resource in a VTF file is the image data. Thumbnails are technically not necessary to load the VTF, although they’re highly recommended to always include.

The thumbnail and image data are now both considered “legacy” resources, appearing in the resource entry list but working exactly as they did before. The only difference is their beginning position in the file, which is now controlled by the resource data field, storing the offset to the thumbnail or image data respectively. The non-legacy resources, if not stored in the header, store a uint32_t just before their data, holding the length of the resource data (including this integer).

Note that due to overzealous optimization, resource entries in the header need to be sorted from lowest numeric resource ID to highest numeric resource ID. I found this out the hard way, and you may not even run into any issues writing unsorted resource entries until a VTF starts to break out of nowhere. Resource entries can be written in any order for VTFs used by the Strata Source engine branch.

This is the full list of VTF resources as of VTF v7.5, sorted lowest to highest.

Resource Name	Resource ID	Stored in Header?	Description of Data
Thumbnail	`"\x01\0\0"` (1)	No	“Legacy” resource, holds thumbnail data.
Particle Sheet	`"\x10\0\0"` (16)	No	If the VTF was created using a particle sheet, this is the particle sheet it used (an SHT file). For the sake of focusing on VTF I will save this format for a possible future post.
Image Data	`"\x30\0\0"` (48)	No	“Legacy” resource, holds image data. Required in all VTFs from v7.3+.
CRC	`"CRC"` (4411971)	Yes	Holds the CRC32 checksum of the input file that `vtex` used to create the VTF, not the VTF itself. Unused by the engine.
Texture LOD Control Info	`"LOD"` (4476748)	Yes	Holds two `uint8_t` integers, the last two bytes of the data field are unused. Controls the highest loaded mipmap when texture detail is set to “High”. For example, if U and V are 11, the highest loaded mipmap on “High” will be 2048x2048 (`2^11`), and on “Very High” the highest loaded mipmap will be 4096x4096 (`2^(11+1)`). There is very little point to this resource’s existence in my opinion.
KeyValues Data	`"KVD"` (4478539)	No	Holds a string which is not null-terminated, specified to be valid KeyValues 1 data. Unused by the engine, is used in third-party tooling to add various information like the texture author and creation date.
Extra Texture Flags	`"TSO"` (5198676)	Yes	Stores extra texture flags, which can be used in mods for game-specific purposes. Unused by the engine in official Valve games, unknown if it’s used in other games. I have never encountered a VTF in the wild with this resource.

As for differences between VTF v7.3, v7.4, and v7.5, v7.3 and v7.4 are functionally identical. As previously stated spheremaps were deprecated in v7.4 and removed in v7.5. v7.5 is unsupported in most Source engine branches before Alien Swarm, but since it’s nearly identical to v7.4, changing the version in the header and adding a dummy spheremap if the texture is a cubemap is enough to convince the engine to load it.

Strata Source VTF (v7.6)

Strata Source, a community-maintained fork of the engine, has made some additions to the format to support CPU compression (usually in tandem with GPU compression), resulting in a new version of the format. VTF v7.6’s header is identical to VTF v7.5.

C++ VTF Header with Compression


#pragma pack(push, 16)
// Bitwise identical
struct VTF_Header_76 : public VTF_Header_75 {};
#pragma pack(pop)

Where v7.6 differs is in the new "AXC" resource, which is optional and sandwiched between the "CRC" and "LOD" resources in the resource entry list.

Resource Name	Resource ID	Stored in Header?	Description of Data
Auxiliary Compression Info	`"AXC"` (4413505)	No	Stores the compression type and strength, as well as the compressed sizes of each individual image. See the description below.

If the "AXC" resource is present, the image data is compressed. The original implementation of the resource looks like this.

C++ First Public "AXC" Resource Iteration


struct AXC_V1 {
// Excluding the size integer present at the beginning of every
// non-legacy resource's data when not stored in the header
uint32_t compressionStrength;
uint32_t compressedSizes[mipCount * frameCount * faceCount];
};

This version of the "AXC" resource always uses the Deflate compression method. The compression strength is unnecessary at runtime, and stores the level of compression used when creating the texture. For Deflate this value can be between -1 and 9, inclusive. If the compression strength is 0, the rest of the resource is ignored, since 0 means no compression took place.

The compressed sizes store the size in bytes of every image that the VTF holds. This is typically calculated from the image dimensions and format, but compression size is non-deterministic so it must be stored. The compressed size layout is as follows. Note that if the texture is a volumetric texture, the entire 3D texture at the given mip, frame, and face level is compressed in one block.

"mipmaps" // 0 - mipCount
{
 "frames" // 0 - frameCount
 {
 "faces" // 0 - number of faces
 { // (either 1, 6, or 7)
 compressed image data length
 }
 }
}

Given this information, it is possible to access the compressed size of an image at a given mip, frame, and face level by using the following formula.

C++ Compressed Image Size Formula


uint32_t compressedSizeAt(AXC_Old axc, uint8_t mip, uint16_t frame, uint8_t face) {
return axc.compressedSizes[
(mipCount - mip - 1) * frameCount * faceCount +
frame * faceCount +
face
];
}

When a VTF is compressed, the position of an image at a given mip, frame, and face level relative to the beginning of the image data resource can be found by summing the sizes of all the compressed images that came before it. The image data is tightly packed (if it wasn’t compression would be rather pointless).

A few years after the introduction of VTF v7.6, I updated it to support Zstd compression in addition to Deflate. From my testing Zstd doesn’t have a significant advantage in compression size, but it does have a significant advantage in decompression speed. The new "AXC" resource looks like this.

C++ Latest Public "AXC" Resource Iteration


struct AXC_V2 {
// Excluding the size integer present at the beginning of every
// non-legacy resource's data when not stored in the header
uint16_t compressionStrength;
uint16_t compressionMethod;
uint32_t compressedSizes[mipCount * frameCount * faceCount];
};

By splitting the compression strength into two shorts, since compression strength was only ever used to store a value between -1 and 9 inclusive, and VTF is stored in little endian, we can take advantage of the empty space to store the compression method in a backwards-compatible way. There are three accepted value ranges for compressionMethod.

<=0: Identifies the first iteration of AXC, using Deflate compression.
8: The latest iteration of AXC, using Deflate compression.
93: The latest iteration of AXC, using Zstd compression.

Note that since the compression strength value is useless at runtime, third-party tooling expecting the old "AXC" resource will continue to work with new Deflate-compressed VTFs. Programs expecting the new "AXC" resource should also load the old AXC resource correctly assuming they handle compressionMethod correctly. For these reasons the resource is not versioned, as making a separate version would actually do more harm than good.

Although minizip-ng is not used in the engine or in any third-party tooling I’ve seen, compressionMethod copies its defines for compression method types. The door is left open for other compression methods, although there’s not much of a point in adding new ones.

Unspoken Requirements / Things to Know

A few VTF requirements aren’t immediately obvious, and sometimes requirements that people will tell you about don’t actually exist. Let’s go over all of them.

Texture Dimensions

Some say a VTF’s image dimensions must not stray from the path of the powers of two. They are utter fools, too cowardly to taste the sweet forbidden fruit of non-PO2 dimensions. Non-PO2 sized textures may not have worked well in the past, but in modern times on modern hardware they are fine, and don’t seem to cause any issues in Source from my testing. Use non-PO2 textures sparingly, but don’t be afraid of them if they’re convenient. (Side note, the dimension for a mip level below an image that has a dimension that doesn’t divide evenly by 2 will be the result of the division plus one (rounded up). For example, if an image has dimensions 111x64, the mip level below that image is expected to have dimensions 56x32.)

That being said, if a VTF is using a compressed format such as DXTn, BCn, or ATIxN its dimensions must be a multiple of 4. Compressed formats require 4x4 pixel blocks throughout the image. This is also why mip levels lower than 4x4 sometimes look very weird for compressed formats.

Spheremaps

Spheremaps are required for VTF cubemaps with a version between v7.1-7.4 inclusive, but they are never used by the engine. If you are making a program to create cubemap VTFs feel free to leave the spheremap blank, or insert a doodle.

Flags

When creating a VTF with no mipmaps, the NOMIP and NOLOD flags should be applied.
When creating a VTF with a format that supports transparency, either the ONEBITALPHA flag or the EIGHTBITALPHA flag must be applied. (Yes, the EIGHTBITALPHA flag actually means multi-bit alpha. It’s a bad name.)
When creating a cubemap VTF, the ENVMAP flag should be applied.

See Appendix A for more information on flags.

Appendix A: More Information on Flags

Most VTF flags are either internal to vtex or internal to the engine. There are a few important ones though. This list covers all the flags the engine uses that are valid to set in a VTF.

v7.0+

Flag	Value	Description
`POINTSAMPLE`	`2^0`	Disable texture filtering when sampling from the texture. Largely obsolete on modern Source branches (CS:GO and up) now that materials can control this.
`TRILINEAR`	`2^1`	Always use trilinear filtering when sampling from the texture.
`CLAMPS`	`2^2`	Do not wrap on the X axis.
`CLAMPT`	`2^3`	Do not wrap on the Y axis.
`ANISOTROPIC`	`2^4`	Always use anisotropic filtering when sampling from the texture.
`NORMAL`	`2^7`	Texture is a normal map.
`NOMIP`	`2^8`	Texture has no mipmaps. Should be present on every texture with 1 mip level.
`NOLOD`	`2^9`	Texture has no LOD (it does not use lower mip levels than the base). This flag is utterly useless and should be present when `NOMIP` is present.
`MINMIP`	`2^10`	Renamed in v7.3. Allows the game to load mip levels with dimensions below 32x32. Should only be used for uncompressed formats, and may introduce performance regressions if used frequently.
`PROCEDURAL`	`2^11`	Texture was either created in code, or will be modified in code.
`ONEBITALPHA`	`2^12`	Should be set for all VTFs storing texture data with one bit alpha.
`EIGHTBITALPHA`	`2^13`	Should be set for all VTFs storing texture data with more than one bit of alpha (ignore the name).
`ENVMAP`	`2^14`	Set if the VTF is storing a cubemap.
`NO_DEBUG_OVERRIDE`	`2^17`	Texture cannot be modified when debugging graphics features are enabled.
`SINGLE_COPY`	`2^18`	Keep only one copy of the texture in memory(?). Unused in later versions of the engine.

v7.2+

Flag	Value	Description
`NO_DEPTH_BUFFER`	`2^23`	Unknown.
`CLAMPU`	`2^25`	Do not wrap on the Z axis.

v7.3+

Flag	Value	Description
`ALL_MIPS`	`2^10`	Unused in v7.5+. Renamed from `MINMIP`.
`VERTEXTEXTURE`	`2^26`	Texture is a vertex texture for `VertexLitGeneric` materials.
`SSBUMP`	`2^27`	Texture is an ssbump.
`BORDER`	`2^29`	Clamp to the texture border color on all axes.

v7.4+

Flag	Value	Description
`SRGB`	`2^6`	Replaced in v7.5. Texture uses the sRGB color space.

v7.4 (TF2-based branches)

Flag	Value	Description
`STAGING_MEMORY`	`2^19`	Unknown.
`IMMEDIATE_CLEANUP`	`2^20`	Unknown.
`IGNORE_PICMIP`	`2^21`	Ignore `mat_picmip` and do not change the maximum mip level.
`STREAMABLE_COARSE`	`2^30`	Enables “coarse” texture streaming.
`STREAMABLE_FINE`	`2^31`	Enables “fine” texture streaming.

v7.5+

Flag	Value	Description
`PWL_CORRECTED`	`2^6`	Texture uses PWL correction (Xbox 360 sRGB approximation).
`SRGB`	`2^19`	Same as the `SRGB` flag from v7.4, just in a different position.
`DEFAULT_POOL`	`2^20`	Unknown.
`MOST_MIPS`	`2^28`	The inverse of `ALL_MIPS`, which is now unused. When enabled, mips below 32x32 will not be loaded.

v7.5+ (CS:GO-based branches)

Flag	Value	Description
`COMBINED`	`2^21`	VTF file is embedded inside a “combined” model. Do not set manually.
`ASYNC_DOWNLOAD`	`2^22`	Unknown.
`SKIP_INITIAL_DOWNLOAD`	`2^24`	Unknown.
`YCOCG`	`2^30`	Unknown.
`ASYNC_SKIP_INITIAL_LOW_RES`	`2^31`	Unknown.

Appendix B: Supported Image Formats

Unfortunately the list of supported formats is not tied to a VTF version, rather it is tied to the the branch of the Source engine you’re using. Fortunately the list of formats common to all branches is fairly extensive. Check the Valve Developer Wiki for a listing with more format-specific information.

SDK2013 is a bit of a dead end in regards to formats, every engine branch created after Alien Swarm should support Alien Swarm’s extra formats in theory (replacing SDK2013’s formats).

This listing also does not include console-specific formats.

All Branches

Format	ID	Extra Information
`RGBA8888`	0
`ABGR8888`	1
`RGB888`	2
`BGR888`	3
`RGB565`	4
`I8`	5	Greyscale, luminance
`IA88`	6	Greyscale, luminance with alpha
`P8`	7	Uses a palette. Unclear how a palette would be specified, likely a holdover from GoldSrc. I haven’t observed this format in any official or unofficial VTFs.
`A8`	8
`RGB888_BLUESCREEN`	9	Identical to `RGB888`, except when the color is `0x0000FF` the color is interpreted as transparent instead.
`BGR888_BLUESCREEN`	10	Identical to `BGR888`, except when the color is `0xFF0000` the color is interpreted as transparent instead.
`ARGB8888`	11
`BGRA8888`	12
`DXT1`	13
`DXT3`	14
`DXT5`	15
`BGRX8888`	16
`BGR565`	17
`BGRX5551`	18
`BGRA4444`	19
`DXT1_ONE_BIT_ALPHA`	20	This format does not function in-game. Use `DXT1` with either alpha flag checked (preferably `ONEBITALPHA`) instead.
`BGRA5551`	21
`UV88`	22
`UVWQ8888`	23
`RGBA16161616F`	24
`RGBA16161616`	25
`UVLX8888`	26
`R32F`	27
`RGB323232F`	28
`RGBA32323232F`	29

Extra SDK2013 Formats

Format	ID	Extra Information
`EMPTY`	36	Should not be used in VTFs, specifies a pixel size of 0 bytes.
`ATI2N`	37	Broken in all Source engine branches except Strata Source.
`ATI1N`	38	Broken in all Source engine branches except Strata Source.

Extra Alien Swarm (and beyond) Formats

Format	ID	Extra Information
`RG1616F`	30
`RG3232F`	31
`RGBX8888`	32
`EMPTY`	33	Should not be used in VTFs, specifies a pixel size of 0 bytes.
`ATI2N`	34	Broken in all Source engine branches except Strata Source.
`ATI1N`	35	Broken in all Source engine branches except Strata Source.
`RGBA1010102`	36
`BGRA1010102`	37
`R16F`	38

Extra Strata Source Formats

Format	ID	Extra Information
`R8`	69	Identical to `I8`, except only using the red channel instead of greyscale.
`BC7`	70
`BC6H`	71	Specifically the signed half-float variant.