Ptex: Introduction to Ptex API

Ptex

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

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.

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.