feat: CUDA/OptiX implementation of TextureSystem

[lgritz]

Most production renderers that use OSL for shading also use OIIO's TextureSystem as their texture engine, and also quite a few non-OSL renderers still use OIIO TextureSystem. But as those renderers add GPU abilities with CUDA and OptiX, they are pretty much on their own when it comes to texture (OSL gives them a customization point where the renderer itself provides texture facilities).

We've talked for some time about OIIO providing a CUDA/OptiX implementation of TS, and it's time to finally get it underway. I think we can get to an MVP in main relatively rapidly, and then continue work to make this a major supported feature.

I would consider the basic design goals to be the following:

• Delivered as part of OIIO somehow, and in a form easily consumable by OSL and other renderers.
• With full feature/quality parity with the existing and future development of the CPU-based OIIO TS (this can happen in stages, with an MVP delivering basic functionality and additions over time getting us to full parity and higher quality).
• With as close as possible an API to existing TS.
• Sharing as much computational code as possible between CPU and GPU implementations.
• Using the OptiX toolkit's on-demand texture loading to provide similar functionality to ImageCache (or maybe as part of, or in conjunction with IC?).

Using this issue to plan, discuss design, track progress, and rally participation from interested parties.

[etheory]

We're definitely interested in contributing @lgritz. @curtisblack and Thibault V would be the representatives on our end at Netflix Animation Studios. Thanks for raising this initiative! We are super excited to get involved.

[lgritz]

Thanks, that's awesome. SPI and NVIDIA and will also be there and ready to pitch in.

Just to repeat here: We will dedicate the next OSL TSC meeting of Oct 23 2pm PT, and the OIIO TSC of Nov 3 2pm PT, to this topic. Visit https://calendar.aswf.io to find zoom links.

[etheory]

Notes from meeting today (this is a braindump, from just the meeting, and some other ideas I had, but it's not an official or final set of notes):

Start initially with testrender in OSL, develop as a group this functionality, then figure out how to move that stuff back into OIIO.

Initial implementation likely to be tied to CUDA + OptiX. But the long term goal would be to support arbitrary platform, abitrary CPU, arbitrary GPU.

Would it be useful to introduce the free-function additions that were added for OSL to OIIO to support things like:

• Mip-map selection
• Shader-based mip-map scaling/editing
• The choice of footprint, be it conical or trapezoidal, or something else
• The filtering method, sample weighting
• Stochastic vs non-stochastic operation

Complicating factors:

• ptex support
• The method that is used to handle the case where a tile is not available, i.e. one colour, lowest mip-map etc. what's a fast way to do this?
• Do we need some change to the API to return true if a tile is available, and false if it isn't to allow the implementation to figure out what to do, or should OIIO do this?
• GPUs are memory constrained, so should OIIO handle the primary memory limiting, or should this be deferred to the implementation in the renderer? Unclear, as everyone had different thoughts on this. I feel that by default OIIO should handle this limiting of memory.

Thanks!

[brechtvl]

For Cycles we're implementing a custom texture system. Probably I won't have time to get involved in this in the near term since the timing didn't work out, but very happy to see this happening.

Our core requirements are perhaps a bit different since we never exposed the more advanced OpenImageIO texture system features to end users, and we support non-NVIDIA GPUs. In case it's useful, this is how I'm trying to optimize performance and memory usage. Somewhat similar to how megatextures work in games.

• Filtering is only bilinear or bicubic, no complex filters like EWA. Assuming that we will take many samples anyway.
• Each tile has border pixels that duplicate pixels from neighboring tiles. Stochastic mip level sampling is used. This makes it possible access a single tile for every texture lookup, with hardware accelerated texture interpolation and no divergence on the GPU.
• We plan to add support for block compression (or even neural texture compression?) in the future, to load more tiles in the same memory. For interactive renders, but also curious how big the difference really is for offline renders.
• For quick loading, the bordered and compressed tiles need to be stored directly in the file, which requires a custom or customized file format.

[aconty]

On the imageworks side I proposed to write an oiio test with a prototype to guide the new system. My plan is to fire AI on this. I'm sharing it here:

GPU Texture System

Create a new test to prototype a new C++ texture system that can work on a GPU.
We will call this GPU "the device", and the only rquirement from it is that it can
run a kernel written in C++. The test will create an executable following the
pattern of the few existing tests that already do that.

The purpose of the test is to simulate execution of a texture system on the device.
For this we will write a class that models the device interface as seen from the
CPU. For now it will just be a fake GPU. Here's an example:

class Device {
    void *alloc(size_t bytes); // Alloc memory on device
    void free(void* p);
    void copy_to(void* device, void* host, size_t bytes);
    void copy_from(void* host, void* device);

    void run(void (*kernel)(int width, int height, void *data);
};

The test will be divided in two cpp files: host.cpp and device.cpp, and the kernel
will live in the latter. Both will be compiled together and linked to OIIO. But
there will be another sanity check: the device.cpp containing the kernel must
compile itself alone to an executable, even if it is useless. This separate binary:

• Can include any OIIO header. BUT ...
• It must not link against OIIO.

And that is or way of ensuring the kernel with the device texture system can
actually run on a GPU.

Test Exercise

The idea of this test is to do a simple operation. A kernel will access two on-disk
textures via file name plus u, v coordinates (with derivatives). It will do a blend
of the two where one uses pixel size derivatives and the other uses something 4
times bigger so we see a blur. Then the output image will be written to disk by the
host side using OIIO.

Purpose of the test

Gather all the functionality we need from OIIO to prototype the texture system so
we can then publish it in OIIO headers one thing at a time. In the first stage, if
something is not yet exposed to be inlined, we will copy&paste it into the test
code. And when we are happy with the result we can start moving code to the official
headers inside OIIO.

General Guidelines

OIIO Style

The common OpenImageIO coding style should be followed and a few existing headers
and sources should be explored. We are going to be borrowing code for texture
filtering and mip mapping, so this should be located first.

Start Simple

This prototype is a proof of concept and we must use use simple approaches like
bilinear texture filtering.

Prepare for Inlining

All tooling code that has to run on the device must be inlined. For later
incorporation in OpenImageIO we will keep it in headers inside the test. If the
implementation is more than a few lines we will split headers in blah_decl.h and
blah_impl.h.

Design

The device texture system uses a launch, fail and retry cycle. This means we try
to run the kernel and if something is missing execution is aborted so the host can
load what the kernel needs. The following data structures are needed:

• A device-side map from ustringhash to texture descriptor. This descriptor holds
  data and display window, as well as mip level ranges. It will also keep a
  pointer to ...
• Another per-texture map from tile coordinates (mip level, x and y) to the
  pixels of the tile, that is float RGB colors.
• A request queue. Requests can be missing textures (file name ustringhash) or
  missing tiles (ustringhash plus tile coordinates).

All this maps are pointerless hash tables that work on the device. Defined as a
template on the Key and Value, they are always created, filled and resized on the
host. Then copyed in just one block to the device. The device kernel can query
them but not modify or grow.

We will use a closed hash (open addressing) with linear probing.

The tile hash map

Tiles are big, so it wouldn't be efficient to store them in a closed hash table.
Instead we will store them in a sidecar vector ordered as they come. Then the hash
map will just store integer offsets into this table.

Example execution

This is the workflow that the test will follow. Starts with completely empty data
structures and:

1. Launches the kernel
2. Kernel tries to read a texture by ustringhash, u, v, etc...
3. Texture is missing. File a request, give up on this pixel.
4. Host finds the kernel failed, handle requests and update tables on device.
5. Repeat

On the second run textures may be found but tiles will be missing so more requests
will be filed for the host to satisfy until the kernel runs to completion. When
the kernel looks up a known texture, it computes the footprint of the filter, and from
that it decides which tiles it needs from what mip levels. Whatever is missing it's
requested and otherwise the lookup is computed and returned.

Main APIs

The texture system lives both on the host and on device. It is a C++ class that starts
on the host keeping:

• The hash map of texture descriptors
• The collection of per-texture hash map of tiles
• The request queue

All of these have identical copies on the device side. It will be structured like this:

// Must work on device
class DTextureSystem {
    class DTile {
        RGB data[64 * 64];
        ...
    };
    class DTex {
        Hash<TileCoords, int> *tiles; // Stores offsets in tilepool
        DTile* tilepool;              // Sidecar for the above hash
        ...
    };

    // This is the target functionality. Compute footprint, get tiles and filter
    RGB lookup(ustringhash, float u, float v, Vec2 du, Vec2 dv);

    Hash<ustringhash, DTex>* textures; // pointerless hashmap
    Queue                    requests; // Missing stuff
};
// Must work on the host
class DTextureSystemHost : public DTextureSystem {
    void synch_to(Device* device); // Uploads part of itself to device
    void handle_requests(); // Loads textures and tiles

    // Extra bookkeeping to map host to device pointers. Free to use
    // the standard and OIIO library
    ...
};

Example Kernel

The device runs the kernel on a grid of pixels with a data pointer.

void blend_kernel(int x, int y, void* data){
    Operation* op = data;
    float resx = float(op->width), resy = float(op->height);
    float u = x / resx, v = y / resy;
    Vec2 derivsA = { 1 / resx, 1 / resy };
    Vec2 derivsB = 4 * derivsA; // Make it blurry
    RGB A = op->texture_system->lookup(op->nameA, u, v, derivsA);
    RGB B = op->texture_system->lookup(op->nameB, u, v, derivsB);
    // We let both lookups run to file as many requests as possible, but now we can
    // early exit.
    if (op->texture_system->failures())
        return;
    op->output_buffer[y * op->width + x] = 0.5 * A + 0.5 * B;
}

The 'Device::run()' method just runs this kernel for all pixels using the usual
two nested loops.

Steps

This is a suggested rough plan

1. Create basic test files, cmake and cpp.
2. Write an implementation of a pointerless hash table.
3. Write unit tests within the existing test that writes, uploads and queries
   the hash. Make sure these unit tests pass.
4. Write and test the launch, fail, repeat cycle.
5. Design the request queue implementation and also unit test it.
6. Gather the filtering functionality that we need for the kernel.
7. Finally write the blending test.

Analysis and Questions

From this point it is AI planning and my answer to its questions. Everything before is human written.

Codebase Analysis

Existing test patterns

Only 2 test suites produce their own executables:

• testsuite/cmake-consumer/ -- standalone CMakeLists.txt, builds consumer target
  linked to OIIO, run via run.py
• testsuite/docs-examples-cpp/ -- standalone CMakeLists.txt, builds 8 executables
  (docs-examples-texturesys, etc.), all linked to both OIIO and Imath

All other 142+ tests are runtest.py-based, using pre-built OIIO tools (testtex, oiiotool, maketx).

The cmake-consumer pattern is closest to what we need: a CMakeLists.txt that builds executables and a run.py that invokes cmake + runs them. Tests are registered in src/cmake/testing.cmake via oiio_add_tests().

No existing test uses a host.cpp / device.cpp split or has one target linked to OIIO and another not.

Key OIIO headers and types for device-side code

GPU-safe headers already in OIIO:

• OpenImageIO/ustring.h -- ustringhash is header-only, stores a single uint64_t, fully constexpr/device-safe
• OpenImageIO/hash.h -- farmhash::inlined::Hash64 is OIIO_HOSTDEVICE constexpr
• OpenImageIO/fmath.h -- fast_sincos, fast_atan2, safe_sqrt, madd, clamp, fast_exp, etc. all OIIO_HOSTDEVICE
• OpenImageIO/platform.h -- OIIO_HOSTDEVICE, OIIO_DEVICE_CONSTEXPR macros
• OpenImageIO/simd.h -- vfloat4, vint4, etc. have scalar fallbacks when OIIO_SIMD is 0
• OpenImageIO/texture.h -- TextureOpt, MipMode, InterpMode, Wrap enums (no GPU annotations, but pure data)

NOT GPU-safe:

• ustring (not ustringhash) -- uses global hash table with mutex/malloc
• SIMD types with OIIO_SIMD > 0 -- use SSE/AVX intrinsics

Types:

• Vec2/Vec3: OIIO wraps Imath (Imath::V2f, Imath::V3f) via OpenImageIO/Imath.h
• RGB color: Imath::C3f (.r, .g, .b) or raw float[3]
• OIIO internally uses simd::vfloat3 (padded to 4) for color accumulation

Texture filtering code location

All in src/libtexture/texturesys.cpp:

• ellipse_axes() -- EWA footprint computation (pure math, ~40 lines)
• anisotropic_aspect() -- anisotropy clamping (in texture_pvt.h, ~35 lines)
• adjust_blur() -- sblur/tblur application
• compute_miplevels() -- mip level selection with blend weights (~80 lines)
• compute_ellipse_sampling() -- sample placement along major axis (~55 lines)
• st_to_texel() -- coordinate to texel mapping (in texture_pvt.h, ~15 lines)
• sample_bilinear() -- bilinear interpolation within a mip level (depends heavily on tile cache, ~200+ lines)
• texture_lookup() -- full EWA anisotropic lookup, orchestrates all of the above (~230 lines)

The tile cache layer (ImageCacheImpl, ImageCacheFile, ImageCacheTile) is the biggest piece that needs adaptation for GPU.

Source textures available in repo

• testsuite/common/textures/grid.tx -- pre-MIP-mapped grid, used by 25+ existing tests
• testsuite/common/textures/checker.tx -- pre-MIP-mapped checkerboard, used by texture-blurtube
• testsuite/common/grid.tif -- 1000x1000 plain TIFF grid, can be maketx'd at runtime
• testsuite/common/checker_with_alpha.exr -- checkerboard with alpha

---

Key Questions

1. Output reference mechanism

Use exr/tif output and image comparison via diff_command in run.py for the blend test.

2. Results onto filesystem

Do not clean up any generated files (output images, build directories) automatically,
the expectation is that run.py leaves artifacts behind for debugging.

3. Source textures

Use the existing testsuite/common/textures/grid.tx and checker.tx (pre-MIP-mapped,
already in repo).

4. Filtering depth

Implement the full EWA/anisotropic footprint pipeline (ellipse_axes, anisotropic_aspect,
compute_miplevels, compute_ellipse_sampling) as in texturesys.cpp.

5. Device realism

The Device class in the SPEC is minimal (alloc, free, copy_to, copy_from, run).
We are going to assume that what you allocate in the device cannot be accessed by the host
and viceversa. But truely it is just a mock-up, copy_to and copy_from will just be
memcpy. But we write the rest of the code as if these pointers were real host, gpu.

6. SIMD vs scalar on device

OIIO's existing texture filtering uses simd::vfloat4 internally (with scalar fallbacks
when OIIO_SIMD is 0). Use only scalar logic and ignore SIMD.

7. RGB and Vec2 types

The SPEC uses RGB and Vec2. These should be:

• RGB → Imath::C3f (.r, .g, .b)
• Vec2 → Imath::V2f (already available via OIIO's Imath dependency).

8. Request queue design

This should be a bool failed flag plus a fixed-size ring buffer of
{request_type, ustringhash, TileCoords} requests. Just with enough space for the
test execution. Note all pixels in rhe kernel run are executed even if one fails. We
want to collect as many requests as possible.

9. Unit test structure

Step 3 says "write unit tests within the existing test." These should be assert-based
self-tests within the main test executable that run before the blend kernel, exiting
non-zero on failure.

10. Tile size

The SPEC shows RGB data[64 * 64] in DTile. OIIO's tile size defaults to 64. Use
64x64 as the hardcoded tile size for now.

11. Pointerless hash table

OIIO has hash.h with farmhash but no pointerless hash table template. Write the
closed-hash/open-addressing/linear-probing table from scratch but using similar patterns.
If possible reuse the same hash functions.

12. Device.cpp compilation sanity check

The device.cpp "must compile itself alone to an executable, even if it is useless."
Do this as a separate build target in the CMakeLists.txt so cmake itself enforces it.

13. Error / failure communication from device to host

The host fetches the request queue. A failure exists if it is not empty.

14. Integration into testing.cmake

texture-device shouldmbe added to the oiio_add_tests() list in
src/cmake/testing.cmake so it's discovered by CTest. This is part of step 1
(creating basic test files).

[aconty]

Forgot to say that's a WIP spec. For instance we can change the tile pool sidecar to be shared by all textures.

[aconty]

A more finished version of the spec can be found here: Spec

[aconty]

A small step towards this: #5228