# wdas/ptex

1 parent 4af1ede commit b3002fb04a237a9d5764b30d0be2dd3f74eaf283 Brent Burley committed Oct 23, 2009
5 .gitignore
 @@ -0,0 +1,5 @@ +install +*.o +*.so +*.a +*.slo
1,287 src/doc/Doxyfile_API_only
78 src/doc/FilterFootprint.html
 @@ -0,0 +1,78 @@ + + + + + Filter Footprint + + +The Ptex filter footprint is specified as two vectors in uv space:
+

+W1 = [uw1, vw1]
+W2 = [uw2, vw2]
+
+
+The vectors form a parallelogram around the sample point, [u, v].
+When the vectors are orthogonal, they form the major and minor axis of +the enclosed ellipse.
+
+

Determining the filter footprint
+

+In general, the vectors represent the uv sampling interval along some +orthogonal axes, a and b:
+
+
[uw1, vw1] = [du/da, dv/da]
+[uw2, vw2] = [du/db, dv/db]
+
+
+Two special cases are of interest:
+
+A) Texture aligned grid (the classic Ptex case) - the vectors form two +sides of a rectangle, uw by vw:
+
+
[uw1, vw1] = [uw, 0]
+[uw2, vw2] = [0, vw]
+
+
+B) Projection from screen space (where a and b are screen coordinates +in pixels):
+

+Given derivatives of the screen coordinates:
+
+
+
da/du = Du(a)
+db/du = Du(b)
+da/dv = Dv(a)
+db/dv = Dv(b)
+
+
+
the vectors can be found by inverting +the Jacobian matrix [da/du, db/du ; da/dv, db/dv]:
+

+det = (da/du * db/dv - db/du * da/dv)
+du/da =  (1/det) * db/dv
+dv/da = -(1/det) * db/du
+du/db = -(1/det) * da/dv
+dv/db =  (1/det) * da/du
+[uw1, vw1] = [du/da, dv/da]
+[uw2, vw2] = [du/db, dv/db]
+
+
+
+
Note: if the ptex u, v coordinates +aren't aligned with the renderer's uv coordinates, the chain rule can +be used.
+Given texture coordinates s and t:
+

+ds/du = Du(s)
+dt/du = Du(t)
+ds/dv = Dv(s)
+dt/dv = Dv(t)
+[uw1, vw1] = [ds/du*du/da + ds/dv*dv/da, dt/du*du/da + dt/dv*dv/da]
+[uw2, vw2] = [ds/du*du/db + ds/dv*dv/db, dt/du*du/db + dt/dv*dv/db]
+
+
+
+
+ +
12 src/doc/Makefile
 @@ -0,0 +1,12 @@ + +.PHONY : all doc doc_api_only + +all: doc_api_only # doc + +doc: + mkdir -p ../../install/doc + doxygen Doxyfile + +doc_api_only: + mkdir -p ../../install/doc_API_only + doxygen Doxyfile_API_only
763 src/doc/PtexFile.html
 @@ -0,0 +1,763 @@ +

Ptex File Format Specification Version 1.2
+

+Revision history:
+ +
1.0
+
9/29/06
+
Initial Release
+
1.1
+
2/27/07
+
"Edit face data" amended to +included precomputed constant value
+
1.2
+
1/5/09
+
Added: subface flag, const +neighborhood flag, u/v border modes, separately stored large metadata +items.
Clarified triangle texture storage.
+
1.2 revised
+
10/20/09
+
Documentation revision only.
+Corrected size of "keysize" and "datatype" in meta data spec to match implementation.
+Temporarily removed unimplemented features: u/v border modes, separately stored large metadata items.
+
+ + + + + + + + + + + + + + + + + + + + + + +
+
+

General Notes:

+
+
• A "face" is one face of a polymesh.  The polymesh has a base +type of either quad or triangle.  For quad meshes, ptex stores +rectangular textures.  For triangle meshes, ptex stores triangular +textures.
+
• +
• Non-quads +embedded in a quad mesh are +subdivided once to generate quad subfaces and textures are stored +per subface.
+
• +
• Every face (or subface) has a unique index, or "faceid", which is +implied by +the ordering in the "Face Info" block.  The faceids are numbered +starting from zero.  Subfaces are ordered in following the edge +order within the parent face.
+
• +
• A "channel" is a scalar data value stored in the file (e.g. one +component of a color).  There can +be any number of channels in the file, but all channels must have the +same data type.  +Channels are stored separately for better compression.
• +
• A "level" is a set of data across all the faces at a particular +resolution.  The first level is the full-res set of data where the +resolution of each face is specified in the "Face Info" +block.  Subsequent levels are power-of-two reductions (i.e. "mip +maps").
+
• +
• One channel may optionally be indicated as the alpha +channel.  When an +alpha +channel is present, the data values in the first level are expected to +be stored +"unmultiplied" (as opposed to being premultiplied with the +alpha).  This choice was made to preserve the original data +in the file for subsequent editing as premultiplying can result in data +loss.  The +tradeoff is that the multiplication must now be handled during +filtering.   Reduction levels are stored premultiplied.
• +
• Compression, where indicated, uses the "deflate" algorithm as +implemented in +zlib's compress and uncompress functions.  Differencing (where +each value is replaced by the difference between the value and the +preceeding value) is used where indicated to achieve +better compression.
+
• +
• All data is stored in "little endian" format.
• +
• Face data is stored in v-major order with the first sample +corresponding to +u=v=0. This is considered the bottom-left corner with u pointing right +and v pointing up.
• +
• Triangle texture data is stored in a specialized layout + (documented elsewhere). The texels are packed into a square texture + for storage. The number of texels is the same as for quad textures + (n-squared texels where n is a power-of-two) though only isotropic + textures are supported (i.e. ures = vres). Storage of the + square-packed triangle textures is identical to quad textures + including tiling, compression, etc.
+
• +
• No padding or data alignment within the file is assumed beyond +what is explicitly specified, though an attempt is made to keep data +aligned within structures.  However, data blocks are not generally +aligned on file offsets due to the variable length nature of the zip +compression.
+
• +
+

+

+

General File Structure

+The file is composed of a number of data blocks stored in the order +listed in the table below: +

+ +

+
description of file contents +(fixed length, will never grow)
+
+
+
Face Info
+
+
Constant Datapre-filtered, constant valued +data for each face
Level Info
+
+
Level Data
+
data for each level
+
Meta Datamiscellaneous data
+
Edit Data
+
incremental edits posted to the +file
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+

+ +
magic
+
char[4]
+
magic identifier = string "Ptex"
+
version
+
uint32
+
version number (=1)
+
meshtype
+
uint32
+
+
datatype
+
uint32
+
0=uint8, 1=uint16, 2=float16, +3=float32
+
alphachan
+
uint32
+
index of alpha channel
+ -1 (0xffffffff) indicates no +alpha channel
+
nchannelsuint16number of data channels
nlevelsuint16number of levels
nfaces
+
uint32
+
number of faces
+
+
uint32
+
+
faceinfo size
+
uint32
+
size of Face Info block
constdata sizeuint32size of Constant Data block
levelinfo size
+
uint32
+
size of Level Info block
(reserved)uint32must be zero
+
leveldata sizeuint64total size of all Level Data +blocks
+
+
uint32
+
on-disk size of Meta Data block +(zipped)
+
+
uint32
+
in-memory size of Meta Data +block (unzipped)
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+Empty for now. +
+
+

Face Info

+
+ +
ures
+
uint8
+
log2(number of samples in u +direction)
+
vres
+
uint8
+
log2(number of samples in v +direction)
+
adjedgesuint8ids of edges on adjacent faces +(0 .. 3) x 4 faces (see notes)
+
flags
+
uint8
+
bit0=constant - all pixels in +face have same value
+bit1=has edits (flag not stored in file, for api use only)
+bit2=constant neighborhood - all neighboring faces have same value as +this face
+bit3=subface - face is a subface
+
+
uint32[4]
+
faceids of adjacent faces (0 .. +nfaces)
+-1 (0xffffffff) indicates a border (no adjacent face)
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +(times number of faces)
+
+Notes:
+
+
• The entire block is zip compressed and the +size is indicated in the header.
• +
• Constant faces (indicated by flag bit0) are only stored in the +Constant Data section and not in the Level Data section.
+
• +
• The "adjedge" values are stored as 2-bit values in +little-endian order (i.e the first entry is stored in the lowest 2 +bits, etc.).
+
• +
• For triangle meshes, the adjface array has only 3 +entries but 4 entries are still +allocated to simplify the implementation (the 4th entry in each case is +0).
• +
• For a face adjacent to a subface, there will always be two +subfaces sharing the edge with the face.  The face's adjface id +must point to the first subface as encountered in a counter-clockwise +traversal of the face.
+
• +
+
+

Constant Data

+The constant data block contains a single value per channel for +each +face.  For non-constant faces, these values represent the average +of the values for each +face.
+
+
• The data block contains the first channel for all the faces (in +faceid +order), then the second channel, etc.
• +
• The entire block is zip +compressed +as a single unit (with no differencing).
• +
• For textures with alpha, the values are stored +un-multiplied.  This is done to exactly preserve the original data +values for constant-valued faces.
• +
• To determine the average value of a non-constant face, the data +are +pre-multiplied with alpha, averaged, and then divided by alpha before +being stored.
+
• +
+
+

Level Info

+The data are grouped into levels with the first level representing the +full-res data for all of the faces, the next level representing a +power-of-two reduction of the first (half the res in both u and v), and +subsequent levels representing half the previous level.  The Level +Info +block lists the number of +faces in the level and size of each level's data.
+
+ +
leveldatasize
+
uint64
+
size of level's data block +(including level data header)
+
+
uint32
+
compressed size of level data +header
+
nfaces
+
uint32
+
number of faces in level
+
+ + + + + + + + + + + + + + + + + +(times number of levels)
+
+Notes:
+
+
• The first level stores faces in faceid order.  Only +non-constant faces are stored, though all the faces are included in the +level data header.
+
• +
• Reduction levels exclude constant faces and store non-constant +faces in largest-to-smallest order +(according to the smaller dimension of each face).  Ordering among +faces with the same smaller-dimension size follows the +original face id +order.  The purpose of this ordering is to allow each level to +remain fully populated as the smallest faces may be omitted from the +level.
• +
• The number of faces in reduction levels may be less than the +total number of faces in the file:
• +
+
• The level data only includes non-constant faces (as indicated +by the +"constant" flag in the face data header).
• +
• As face resolutions are reduced, small faces may be omitted +from further reduction levels.
+
• +
+
+
+
+
+

Level Data

+Each Level Data block (one per level) consists of a header containing a +list of face sizes +followed by a +number of face data blocks of the given sizes.  Non-constant +face data is packed (with channels separated) +and then optionally differenced and compressed.
+
+ +
facesize
+
uint32 (bits 0..29)
+
sizes of data block for each face
+
encoding
+
bits 30..31 of facesize
+
0 = constant valued (1 sample +per channel)
+1 = zip compressed
+2 = zip compressed w/ differencing
+3 = tiled
+
+ + + + + + + + + + + + +(times number of faces in level)
+
+For tiled faces, the face data begins with the following pre-header:
+ +
tileures
+
uint8
+
log2(number of samples per tile +in u +direction)
+
tilevres
+
uint8
+
log2(number of samples per tile +in v +direction)
+
+
uint32
+
+
+ + + + + + + + + + + + + + + + + +
+and is followed by a compressed header listing the tile sizes and +encodings:
+ +
tilesizes
+
uint32 (bits 0..29)
+
sizes of data block for each tile
+
encoding
+
bits 30..31 of tilesize
+
0 = constant valued (1 sample +per channel)
+1 = zip compressed
+2 = zip compressed w/ differencing
+ + + + + + + + + + + + +(times number of tiles in face)
+
+Each tile is then stored separately (with tiles in v-major order) in +the same manner as the untiled face data.  Note: the number of +tiles for a face is determined by comparing the tile_ures and tile_vres +with the ures and vres of the face. +
+
+
+

Meta Data
+

+Miscellaneous application defined data.  Possibilities include +channel names, timestamp, software settings, 3d vertex data, etc.  +The +meta data is a stream of individual data blocks.
+
+Meta data block
+ +
keysize
+
uint8
+
length of key string (including +null)
+
key
+
uint8[keysize]
+
ascii character string +(null-terminated)
+
datatype
+
uint8
+
0=ascii, 1=int8, 2=int16, +3=int32, 4=float, 5=double
+
datasize
+
uint32
+
size of data block (in bytes)
+
data
+
uint8[datasize]
+
data block
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
• The entire stream of data blocks is compressed as a whole.  +The compressed and uncompressed sizes are both stored in the header.
• +
• Ascii characters strings (both the key and "ascii" data values) +are stored null-terminated.  The size includes the null character.
+
• +
+
+

Edit Data

+The edit data block includes incremental data edits that are pending to +be applied to the file.  The format is designed to allow appending +edit blocks to a file without otherwise affecting the file.
+
+Edit data block
+ +
edittype
+
uint8
+
1=edit face data, 2=edit meta +data
+
editsize
+
uint32
+
size of editdata block
+
editdata
+
(variable)
+
based on edit type
+
+ + + + + + + + + + + + + + + + + +
+Edit face data
+ +
faceid
+
uint32index of face
+
faceinfo
+
FaceInfo block
+
(as described in FaceInfo +section)
+
facesize & encoding
+
uint32(as described in Level Data +section)
+
constval
+
uint8[pixelsize]
+
constant value (average pixel +value, as described in Constant Data section)
+
facedata
+
uint8[facesize]
+
encoded data block
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Edit meta data
+ +
+
uint32
+
compressed size of meta data
+
+
uint8[metazipsize]
+
one or more data blocks (as +described in Meta Data section)
+
+ + + + + + + + + + + + + + + + + +
+
 @@ -0,0 +1,4 @@ +API documentation is generated via doxygen (www.doxygen.org). +Two versions are generated, one for the public api only, +installed into ../../install/doc_API_only, and the other +with a full source code index in ../../install/doc.
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
40 src/doc/apiintro.txt
 @@ -0,0 +1,40 @@ +/** +\page apiintro Introduction to Ptex API + +The %Ptex API consists of a set of abstract interface classes, +PtexCache, PtexTexture, PtexWriter, PtexFilter, etc., that +have special methods for construction and destruction as +described below. + +%Ptex API objects have no public constructors. Because the +classes are abstract, they cannot be constructed directly. Objects of +a given type must be obtained through some other interface, either a +static method on that class or from some other object that manages +instances of that class. For example, PtexFilter instances of +different types are obtained via the static PtexFilter::getFilter() +method, and PtexTexture instances are obtained either through a +PtexCache instance or via the static PtexTexture::open() method if a +cache isn't being used. + +%Ptex API objects have no public destructors. By design, the +destructors of API objects are protected and instances may not be +directly destroyed or deleted. Instead, applications that use the API +are expected to release objects back to the API by calling the release +method on each object. The release method in some cases just calls +delete on the object, but in most cases objects are returned to the +cache and may be reused if they are requested again later. Also, most +of the objects can be shared, even among different threads, so the +release method frequently will just decrement a reference count and +return. + +By defining all API objects method to use release() instead of delete, +a consistent interface is provided and the implementation can choose +how to manage each object's lifetime as it chooses. + +The PtexPtr template can hold and release API objects +automatically. Use of PtexPtr makes it easy to use the API +correctly. See the PtexPtr documentation page for details and an +example. + +*/ +
48 src/doc/intro.txt
 @@ -0,0 +1,48 @@ +/** +\page intro Introduction to Ptex + +%Ptex is a texture mapping system that uses the intrinsic per-face UVs +of a poly mesh. No explicit UV assignment is required. Textures are +stored along with adjacency data in a single texture file per surface. +%Ptex uses the adjacency data to perform seamless anisotropic filtering +of multi-resolution textures across surfaces of arbitrary topology. + +The %Ptex API provides the ability to read and write ptex files, access +texture data through a memory-managed cache, and apply various filters +to the data. The API is designed to allow easy integration with +production renderers such as PRMan. + +Technical information about %Ptex filtering is available in the paper: + +%Ptex: Per-Face Texture Mapping for Production Rendering, Burley and Lacewell, +Eurographics Symposium on Rendering 2008. + +\image html "ptex-teaser.jpg" + +T. Rex with 2694 faces rendered with %Ptex. No explicit UV assignment +was used. The largest texture layer, the fine-scale displacements, has +836 million texels stored in a single %Ptex file with individual face +resolutions ranging from 64 x 64 to 2048 x 2048 texels. No seams are +visible across faces, even under close magnification. ((c) Walt Disney +Animation Studios) + +Abstract: + +Explicit parameterization of subdivision surfaces for texture mapping +adds significant cost and complexity to film production. Most +parameterization methods currently in use require setup effort, and +none are completely general. We propose a new texture mapping method +for Catmull-Clark subdivision surfaces that requires no explicit +parameterization. Our method, %Ptex, stores a separate texture per quad +face of the subdivision control mesh, along with a novel per-face +adjacency map, in a single texture file per surface. %Ptex uses the +adjacency data to perform seamless anisotropic filtering of +multi-resolution textures across surfaces of arbitrary topology. Just +as importantly, %Ptex requires no manual setup and scales to models of +arbitrary mesh complexity and texture detail. %Ptex has been +successfully used to texture all of the models in an animated +theatrical short and is currently being applied to an entire animated +feature. %Ptex has eliminated UV assignment from our studio and +significantly increased the efficiency of our pipeline. +*/ +
38 src/doc/main.txt
 @@ -0,0 +1,38 @@ +/** \mainpage Ptex + +\section mainapi Main API pages + - Ptex - Common data structures and enums used throughout the API. + - PtexCache - Create a cache for reading one or more ptex files. + - PtexTexture - Access data from a ptex file. + - PtexFaceData - Access per-face texture data from a PtexTexture. + - PtexMetaData - Access meta data from a PtexTexture. + - PtexWriter - Create or update a ptex file. + - PtexFilter - Apply a filter to ptex data. + - PtexPtr - Use a smart pointer to automatically hold and release API objects. + +\section addtionaldocs Additional documenatation pages +- \subpage license +- \subpage intro +- \subpage apiintro +- \subpage adjdata +- \subpage filterfootprint +- \subpage tritex +- \subpage fileformat +- \subpage metadata +*/ + +/** +\page license License +\verbinclude License.txt +*/ + +/** +\page fileformat Ptex File Format Specification +\htmlinclude PtexFile.html +*/ + +/** +\page filterfootprint Filter Footprint +\image html uvellipse.png +\htmlinclude FilterFootprint.html +*/
 @@ -0,0 +1,41 @@ +/** +\page metadata Standard Ptex meta data keys + +Meta data keys that begin with "Ptex" are reserved. Standard %Ptex +keys are documented in the following table. + + +
KeyTypeDescriptionCount
PtexFaceVertCountsint32Number of vertices for each face.one value per face
PtexFaceVertIndicesint32Index of each face vert within PtexVertPositions array.one value per vertex per face
PtexVertPositionsfloat3d position of each vertex.three values per vertex
+ + + + + + + + + + + + + + + + + + + + +The PtexFaceVertCounts, PtexFaceVertIndices, and PtexVertPositions can +be used to describe geometry on which the %Ptex texture can be mapped. +This data isn't used directly by the %Ptex library but can be used by +3d painting programs, %Ptex texture viewers, or similar applications. + +Notes: + - The faceids and per-face UVs used to map the %Ptex texture data + are implied by the face and vertex ordering listed in these keys. + - Non-quad faces are allowed. They are not required to be subdivided + into quad subfaces as with the texture data. Thus, the faceids in + the texture data may not match the entries in the meta data exactly, + though they will be in the same order. +*/
BIN src/doc/ptex-teaser.jpg
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
BIN src/doc/tritex.pdf
Binary file not shown.
BIN src/doc/tritex.png