| Title: | Per-Face Texture Mapping for 3D Rendering |
|---|---|
| Description: | Reads, writes, and filters per-face textures using 'Ptex' <https://github.com/wdas/ptex>. Stores textures on individual mesh faces without a global texture atlas. Provides filtering across face boundaries, shared texture caches, and a native runtime interface. |
| Authors: | Tyler Morgan-Wall [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-3131-3814>), Disney Enterprises, Inc. [aut, cph] (Ptex library) |
| Maintainer: | Tyler Morgan-Wall <[email protected]> |
| License: | BSD_3_clause + file LICENSE |
| Version: | 2.5.4-1 |
| Built: | 2026-11-16 06:18:08 UTC |
| Source: | https://github.com/tylermorganwall/ptexr |
Returns the versioned C function table for downstream packages. See
system.file("runtime-api.txt", package = "ptexr") for integration details.
The table is obtained on R's main thread; its native operations can then
run on worker threads without invoking R. Keep the handle alive until all
native resources and workers using it have finished. Explicitly unloading
the package DLL while consumers exist is unsupported.
ptex_api()ptex_api()
An external pointer tagged ptex.api.v1. It cannot be serialized.
api = ptex_api()api = ptex_api()
Memory and open-file limits are soft limits on retained cache data, not hard bounds on process memory. Concurrent lookups can temporarily exceed them. File references are returned after each lookup, so live texture handles do not prevent normal cache eviction.
ptex_cache(max_files = 100L, max_memory = 256 * 1024^2, premultiply = TRUE)ptex_cache(max_files = 100L, max_memory = 256 * 1024^2, premultiply = TRUE)
max_files |
Default |
max_memory |
Default |
premultiply |
Default |
An external pointer owning a cache. Use ptex_close() to release it.
cache = ptex_cache(max_memory = 32 * 1024^2) ptex_cache_info(cache) ptex_close(cache)cache = ptex_cache(max_memory = 32 * 1024^2) ptex_cache_info(cache) ptex_close(cache)
Inspect Cache Usage
ptex_cache_info(cache)ptex_cache_info(cache)
cache |
A cache from |
A named numeric vector of memory bytes, file counts and block reads.
Close a Texture or Cache
ptex_close(handle)ptex_close(handle)
handle |
A texture or cache handle. Closing an already closed handle is safe. |
Invisibly NULL.
Inspect Face Resolution and Adjacency
ptex_face_info(texture, face)ptex_face_info(texture, face)
texture |
A texture from |
face |
One-based face index. |
A list with width, height, adjacent face and edge indices (one-based; zero means a boundary face), and the subface flag. Triangles use three edges.
Inspect a Ptex Texture
ptex_info(texture)ptex_info(texture)
texture |
A texture from |
A list with mesh and data types, face and channel counts, alpha channel (one-based, or zero for no alpha), and border modes.
Reuse one cache for a collection of textures. The file is loaded lazily; opening it does not decode every face. Textures keep their cache alive even after its R handle is explicitly closed. File contents must remain unchanged while cached; use a new cache after rewriting a file.
ptex_open(path, cache = ptex_cache())ptex_open(path, cache = ptex_cache())
path |
Path to a Ptex file. |
cache |
Default |
An external pointer owning a texture reference. Handles cannot be serialized; reopen files in a new R session.
file = tempfile(fileext = ".ptx") ptex_write(file, list(array(c(0.1, 0.7, 0.9), c(1, 1, 3)))) texture = ptex_open(file) ptex_info(texture) ptex_sample(texture, face = 1, uv = c(0.5, 0.5)) ptex_close(texture) unlink(file)file = tempfile(fileext = ".ptx") ptex_write(file, list(array(c(0.1, 0.7, 0.9), c(1, 1, 3)))) texture = ptex_open(file) ptex_info(texture) ptex_sample(texture, face = 1, uv = c(0.5, 0.5)) ptex_close(texture) unlink(file)
Filters use the file's face adjacency to blend across seams. The footprint
is a parallelogram with sides (du1, dv1) and (du2, dv2) in local face
coordinates, typically derived from ray differentials. A zero footprint
still permits reconstruction filtering. filter = "point" reads the nearest
texel without blending. No gamma, sRGB or other colour conversion is applied;
integer formats are normalized by Ptex to the range zero to one.
ptex_sample( texture, face, uv, footprint = c(0, 0, 0, 0), filter = "bspline", first_channel = 1L, channels = NULL, lerp = TRUE, sharpness = 0, no_edge_blend = FALSE )ptex_sample( texture, face, uv, footprint = c(0, 0, 0, 0), filter = "bspline", first_channel = 1L, channels = NULL, lerp = TRUE, sharpness = 0, no_edge_blend = FALSE )
texture |
A texture from |
face |
One-based face indices, one per sample, or one index for all samples. |
uv |
Two-column matrix of local |
footprint |
Default |
filter |
Default |
first_channel |
Default |
channels |
Default |
lerp |
Default |
sharpness |
Default |
no_edge_blend |
Default |
A numeric matrix with one row per sample and one column per channel.
# A little two-tone flag, sampled at the centres of its four texels. file = tempfile(fileext = ".ptx") flag = array(c(1, 0, 1, 0, 0.1, 0.7, 0.1, 0.7, 0.2, 1, 0.2, 1), c(2, 2, 3)) ptex_write(file, list(flag)) texture = ptex_open(file) ptex_sample(texture, 1, as.matrix(expand.grid(u = c(.25, .75), v = c(.25, .75))), filter = "point") ptex_close(texture) unlink(file)# A little two-tone flag, sampled at the centres of its four texels. file = tempfile(fileext = ".ptx") flag = array(c(1, 0, 1, 0, 0.1, 0.7, 0.1, 0.7, 0.2, 1, 0.2, 1), c(2, 2, 3)) ptex_write(file, list(flag)) texture = ptex_open(file) ptex_sample(texture, 1, as.matrix(expand.grid(u = c(.25, .75), v = c(.25, .75))), filter = "point") ptex_close(texture) unlink(file)
Ptex Library Version
ptex_version()ptex_version()
The bundled upstream Ptex version as a character string.
ptex_version()ptex_version()
Writes an entire file with mipmaps. Each face is an array indexed by
[u, v, channel] with power-of-two spatial dimensions. All faces use the
same number of channels. Triangle textures use Ptex's square texel layout;
sampling coordinates occupy u >= 0, v >= 0, u + v <= 1.
ptex_write( path, faces, mesh_type = "quad", adjacent_faces = NULL, adjacent_edges = NULL, alpha_channel = 0L, overwrite = FALSE )ptex_write( path, faces, mesh_type = "quad", adjacent_faces = NULL, adjacent_edges = NULL, alpha_channel = 0L, overwrite = FALSE )
path |
Destination file path. |
faces |
Nonempty list of numeric |
mesh_type |
Default |
adjacent_faces |
Default |
adjacent_edges |
Default |
alpha_channel |
Default |
overwrite |
Default |
Adjacent face and edge matrices must describe reciprocal connections. Quad edges run counterclockwise from the bottom edge: bottom, right, top, left. Triangle edges follow Ptex's native order. This writer does not author subfaces or arbitrary metadata; existing files containing them can be read. Values are stored as floats with no colour conversion and should contain unassociated colour when an alpha channel is specified.
Invisibly the normalized output path.
# A warm face and a cool face, joined along their shared edge. file = tempfile(fileext = ".ptx") faces = list(array(c(.9, .2, .05), c(1, 1, 3)), array(c(.05, .3, .9), c(1, 1, 3))) neighbours = matrix(0L, 2, 4) edges = matrix(1L, 2, 4) neighbours[1, 2] = 2L; edges[1, 2] = 4L neighbours[2, 4] = 1L; edges[2, 4] = 2L ptex_write(file, faces, adjacent_faces = neighbours, adjacent_edges = edges) texture = ptex_open(file) ptex_sample(texture, c(1, 2), rbind(c(1, .5), c(0, .5)), footprint = c(.2, 0, 0, .2)) ptex_close(texture) unlink(file)# A warm face and a cool face, joined along their shared edge. file = tempfile(fileext = ".ptx") faces = list(array(c(.9, .2, .05), c(1, 1, 3)), array(c(.05, .3, .9), c(1, 1, 3))) neighbours = matrix(0L, 2, 4) edges = matrix(1L, 2, 4) neighbours[1, 2] = 2L; edges[1, 2] = 4L neighbours[2, 4] = 1L; edges[2, 4] = 2L ptex_write(file, faces, adjacent_faces = neighbours, adjacent_edges = edges) texture = ptex_open(file) ptex_sample(texture, c(1, 2), rbind(c(1, .5), c(0, .5)), footprint = c(.2, 0, 0, .2)) ptex_close(texture) unlink(file)