Ptex: per-face texture mapping without UV assignment

One texture per face, with no UV assignment

Ptex was developed by Walt Disney Animation Studios for production-quality rendering, and its central claim is blunt: no UV assignment is required. The library applies a separate texture to each face of a subdivision or polygon mesh, which removes the chart-painting stage that usually dominates the cost of preparing a texture set for a production asset.

The format follows from that decision. A single Ptex file can store hundreds of thousands of texture images, so a shot can arrive as one file rather than a directory of loose images that a renderer has to open, stat and cache by itself. The API layer adds cached file I/O and high-quality filtering, and the README points at that combination as the reason a production-quality renderer or a texture authoring application can take Ptex on without reimplementing the plumbing.

The audience is therefore pipeline engineers and renderer developers inside studios that already handle dense, subdivided geometry. For a web project shipping a handful of meshes, the whole idea is more machinery than the problem needs.

make is a thin wrapper over cmake, not a separate build system

Building on Linux takes four make targets, and the README lists them in the order you would run them:

    make prefix=$PWD/install
    make test
    make install
    make doc

The Makefile itself states that it uses cmake under the hood, so there is no separate build system to learn. The prefix argument decides where the tree lands; without it the Makefile derives a default path from the output of uname and the build flavor. The wrapper also auto-detects ninja and falls back to Unix Makefiles when NO_NINJA=1 is set. Verbose output comes from V=1 or VERBOSE=1, and FLAVOR or BUILD_TYPE selects the cmake build type.

Tests are wired into the default target, so an ordinary build already runs them. To narrow that run, the flags variable is forwarded to ctest, and the README shows how to run only the half tests:

        make test flags='-R half'

Documentation is a separate concern. The doc target only produces output when Doxygen and Graphviz are installed on the machine.

What actually installs: one binary and four headers

The install tree is small, and the README spells out its contents exactly:

    install/bin:
        ptxinfo
    install/include:
        PtexHalf.h  PtexInt.h  Ptexture.h  PtexUtils.h
    install/lib:
        libPtex.a  libPtex.so

That is the whole surface area a consumer touches: a command line utility for inspecting Ptex files, a static and a shared build of the library, and the headers needed to call it. There is no plugin directory, no format converter and no texture authoring program in that list.

The source tree follows a similar logic, with the library in src/ptex, command line utilities in src/utils, the unit tests in src/tests and documentation in src/doc. The README also notes that docs land in the src/doc/ptex directory during the build and are installed under install/share/doc/ptex. The public website lives on a separate gh-pages branch rather than in the main tree, and release notes for new versions are added there through a buildsite.py script.

Per-face files against the UV atlas alternative

The standard alternative to Ptex is the one it is named against: a single atlas image plus a set of UV coordinates per mesh, where artists cut and pack islands into a shared texture. The difference in approach is not cosmetic. With an atlas, resolution is a shared budget, so a character with a detailed face spends from the same pool as a plain wall, and the artist has to keep the chart valid every time the mesh changes. With Ptex, every face owns its own image at its own resolution, and the face count, not the chart, determines the file count.

That trade runs the other way too. A per-face scheme needs one texture per face, which means more data to author and more files to track, while an atlas keeps everything in one image that any tool can open. The README positions Ptex for the case where mesh density is the expensive thing, and it does not argue that this is universally the better choice.

For a team already shipping UV atlases through a working pipeline, Ptex is a migration with real texture rework behind it, not a drop-in library call.

The hardcoded version number breaks tarball builds

Ptex's build scripts carry a hardcoded version number that can disagree with the tagged release when the code is built from a tarball rather than from a git worktree. The escape hatch is a plain file named version at the root of the source tree, and the README shows how to write one:

    echo v2.3.2 >version

When that file exists it takes precedence over both the git tags and the PTEX_VER cmake variable. The failure mode is quiet in a bad way: nothing crashes, the version simply reads wrong, and a studio shipping binaries to artists can end up with two different builds claiming to be the same release.

Release preparation has a matching tool. Before cutting a new minor version, the README asks you to run:

        ./src/tests/check_version --update vX.Y

That script updates the default PTEX_VER in CMakeLists.txt. Run without arguments, check_version.sh warns when the git tags do not match the default version, which is the cheapest way to catch the drift before a release goes out.

What the documentation leaves open

Several questions a new user would ask have no answer in the README. There is no documented rollback procedure, and no release checklist beyond the version tooling described above. The quickstart is labelled for Linux, and no other platform build is covered there.

Licensing is the item that deserves the most attention from a studio. The project is published under a custom licence that GitHub cannot classify, listed simply as Other, so the LICENSE file at the repository root is the only place the real terms live. Anyone planning to ship Ptex inside a renderer distributed to artists, or to a hosted rendering service, needs to read that file and have it reviewed.

There is also a compatibility switch for one specific renderer lineage: setting PRMAN_15_COMPATIBLE_PTEX=1 turns on a cmake option of the same name, which the Makefile passes through as -DPRMAN_15_COMPATIBLE_PTEX:BOOL=TRUE. Its purpose is not explained further in the README, so treat it as an opt-in flag with an unknown scope rather than a documented feature.

Last push on 2026-09-04 and the cost of an upgrade

The repository is not archived, and the last push was on 2026-09-04, the same day the v2.5.4 release was tagged. That is recent enough to treat the project as receiving upstream work rather than as a frozen snapshot, and it also means the version bumps are frequent enough to plan for.

An upgrade is a rebuild and a relink rather than a package install. The library ships as libPtex.a and libPtex.so, and consumers compile against the headers in install/include, so each new upstream release means rebuilding the library on your own build machines and checking that your renderer code still compiles against the current headers. There is no stability guarantee stated in the README for the C API.

Practical consequence: keep Ptex as a pinned build artifact inside your own release pipeline, with the upstream tag recorded, rather than tracking the repository tip. Pinning also sidesteps the tarball version problem described earlier, because a git checkout can always resolve its own tags.

Editorial conclusion

Studios with dense subdivision surfaces and existing texture pipeline tooling get the most from Ptex, and anyone embedding it should budget for the custom licence in the LICENSE file and for rebuilding the library on each upstream version bump. Do not adopt it for small web assets where a normal UV atlas is simpler, or if you need a texture painting application, since the project ships a library and one inspection utility, not an authoring tool. Before committing, verify the licence terms with your own counsel, confirm that ptexinfo can read the production assets you already have, and check the four installed headers against the renderer code you intend to modify.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. wdas/ptex on GitHub