Ptexture.h

Go to the documentation of this file.

#ifndef Ptexture_h
#define Ptexture_h

/*
PTEX SOFTWARE
Copyright 2014 Disney Enterprises, Inc.  All rights reserved

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.

  * The names "Disney", "Walt Disney Pictures", "Walt Disney Animation
    Studios" or the names of its contributors may NOT be used to
    endorse or promote products derived from this software without
    specific prior written permission from Walt Disney Pictures.

Disclaimer: THIS SOFTWARE IS PROVIDED BY WALT DISNEY PICTURES AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE, NONINFRINGEMENT AND TITLE ARE DISCLAIMED.
IN NO EVENT SHALL WALT DISNEY PICTURES, THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND BASED ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
*/

#include "PtexExports.h"
#include "PtexInt.h"
#include "PtexVersion.h"

#include <ostream>

#if !defined(PTEX_PLATFORM_WINDOWS)
#  ifndef DOXYGEN
#    define PTEX_USE_STDSTRING
#  endif
#endif

#ifdef DOXYGEN

namespace Ptex {
#else
PTEX_NAMESPACE_BEGIN
#endif

enum MeshType {
     mt_triangle,               
     mt_quad                    
 };

enum DataType {
    dt_uint8,           
    dt_uint16,          
    dt_half,            
    dt_float            
};

enum EdgeFilterMode {
    efm_none,           
    efm_tanvec          
};

enum BorderMode {
    m_clamp,            
    m_black,            
    m_periodic          
};

enum EdgeId {
    e_bottom,           
    e_right,            
    e_top,                      
    e_left                      
};

enum MetaDataType {
    mdt_string,         
    mdt_int8,           
    mdt_int16,          
    mdt_int32,          
    mdt_float,          
    mdt_double          
};

PTEXAPI const char* MeshTypeName(MeshType mt);

PTEXAPI const char* DataTypeName(DataType dt);

PTEXAPI const char* BorderModeName(BorderMode m);

PTEXAPI const char* EdgeFilterModeName(EdgeFilterMode m);

PTEXAPI const char* EdgeIdName(EdgeId eid);

PTEXAPI const char* MetaDataTypeName(MetaDataType mdt);

inline int DataSize(DataType dt) {
    static const int sizes[] = { 1,2,2,4 };
    return sizes[dt];
}

inline float OneValue(DataType dt) {
    static const float one[] = { 255.f, 65535.f, 1.f, 1.f };
    return one[dt];
}

inline float OneValueInv(DataType dt) {
    static const float one[] = { 1.f/255.f, 1.f/65535.f, 1.f, 1.f };
    return one[dt];
}

PTEXAPI void ConvertToFloat(float* dst, const void* src,
                            Ptex::DataType dt, int numChannels);

PTEXAPI void ConvertFromFloat(void* dst, const float* src,
                              Ptex::DataType dt, int numChannels);

struct Res {
    int8_t ulog2;               
    int8_t vlog2;               

    Res() : ulog2(0), vlog2(0) {}

    Res(int8_t ulog2_, int8_t vlog2_) : ulog2(ulog2_), vlog2(vlog2_) {}

    Res(uint16_t value) : ulog2(int8_t(value&0xff)), vlog2(int8_t((value>>8)&0xff)) {}

    int u() const { return 1<<(unsigned)ulog2; }

    int v() const { return 1<<(unsigned)vlog2; }

    uint16_t val() const { return uint16_t(ulog2 | (vlog2<<8)); }

    int size() const { return u() * v(); }

    size_t size64() const { return size_t(u()) * v(); }

    bool operator==(const Res& r) const { return r.ulog2 == ulog2 && r.vlog2 == vlog2; }

    bool operator!=(const Res& r) const { return !(r==*this); }

    bool operator>=(const Res& r) const { return ulog2 >= r.ulog2 && vlog2 >= r.vlog2; }

    Res swappeduv() const { return Res(vlog2, ulog2); }

    void swapuv() { *this = swappeduv(); }

    void clamp(const Res& r) {
        if (ulog2 > r.ulog2) ulog2 = r.ulog2;
        if (vlog2 > r.vlog2) vlog2 = r.vlog2;
    }

    int ntilesu(Res tileres) const { return 1<<(ulog2-tileres.ulog2); }

    int ntilesv(Res tileres) const { return 1<<(vlog2-tileres.vlog2); }

    int ntiles(Res tileres) const { return ntilesu(tileres) * ntilesv(tileres); }
};

struct FaceInfo {
    Res res;            
    uint8_t adjedges;       
    uint8_t flags;              
    int32_t adjfaces[4];        

    FaceInfo() : res(), adjedges(0), flags(0)
    {
        adjfaces[0] = adjfaces[1] = adjfaces[2] = adjfaces[3] = -1;
    }

    FaceInfo(Res res_) : res(res_), adjedges(0), flags(0)
    {
        adjfaces[0] = adjfaces[1] = adjfaces[2] = adjfaces[3] = -1;
    }

    FaceInfo(Res res_, int adjfaces_[4], int adjedges_[4], bool isSubface_=false)
        : res(res_), flags(isSubface_ ? flag_subface : 0)
    {
        setadjfaces(adjfaces_[0], adjfaces_[1], adjfaces_[2], adjfaces_[3]);
        setadjedges(adjedges_[0], adjedges_[1], adjedges_[2], adjedges_[3]);
    }

    EdgeId adjedge(int eid) const { return EdgeId((adjedges >> (2*eid)) & 3); }

    int adjface(int eid) const { return adjfaces[eid]; }

    bool isConstant() const { return (flags & flag_constant) != 0; }

    bool isNeighborhoodConstant() const { return (flags & flag_nbconstant) != 0; }

    bool hasEdits() const { return false; }

    bool isSubface() const { return (flags & flag_subface) != 0; }

    void setadjfaces(int f0, int f1, int f2, int f3)
    { adjfaces[0] = f0, adjfaces[1] = f1, adjfaces[2] = f2; adjfaces[3] = f3; }

    void setadjedges(int e0, int e1, int e2, int e3)
    { adjedges = (uint8_t)((e0&3) | ((e1&3)<<2) | ((e2&3)<<4) | ((e3&3)<<6)); }

    enum { flag_constant = 1, flag_obsolete = 2, flag_nbconstant = 4, flag_subface = 8 };
};


#ifdef PTEX_USE_STDSTRING
typedef std::string String;
#else
class String
{
public:
    String() : _str(0) {}
    String(const String& str) : _str(0) { *this = str; }
    PTEXAPI ~String();
    PTEXAPI String& operator=(const char* str);
    String& operator=(const String& str) { *this = str._str; return *this; }
    String& operator=(const std::string& str) { *this = str.c_str(); return *this; }
    const char* c_str() const { return _str ? _str : ""; }
    bool empty() const { return _str == 0 || _str[0] == '\0'; }

private:
    char* _str;
};
#endif

#ifndef PTEX_USE_STDSTRING
PTEXAPI std::ostream& operator << (std::ostream& stream, const Ptex::String& str);
#endif


#ifdef DOXYGEN
} // end namespace Ptex
#endif

class PtexMetaData {
 protected:
    virtual ~PtexMetaData() {}

 public:
    virtual void release() = 0;

    virtual int numKeys() = 0;

    virtual void getKey(int index, const char*& key, Ptex::MetaDataType& type) = 0;

    virtual bool findKey(const char* key, int& index, Ptex::MetaDataType& type) = 0;

    virtual void getValue(const char* key, const char*& value) = 0;

    virtual void getValue(int index, const char*& value) = 0;

    virtual void getValue(const char* key, const int8_t*& value, int& count) = 0;

    virtual void getValue(int index, const int8_t*& value, int& count) = 0;

    virtual void getValue(const char* key, const int16_t*& value, int& count) = 0;

    virtual void getValue(int index, const int16_t*& value, int& count) = 0;

    virtual void getValue(const char* key, const int32_t*& value, int& count) = 0;

    virtual void getValue(int index, const int32_t*& value, int& count) = 0;

    virtual void getValue(const char* key, const float*& value, int& count) = 0;

    virtual void getValue(int index, const float*& value, int& count) = 0;

    virtual void getValue(const char* key, const double*& value, int& count) = 0;

    virtual void getValue(int index, const double*& value, int& count) = 0;
};


class PtexFaceData {
 protected:
    virtual ~PtexFaceData() {}

 public:
    virtual void release() = 0;

    virtual bool isConstant() = 0;

    virtual Ptex::Res res() = 0;

    virtual void getPixel(int u, int v, void* result) = 0;

    virtual void* getData() = 0;

    virtual bool isTiled() = 0;

    virtual Ptex::Res tileRes() = 0;

    virtual PtexFaceData* getTile(int tile) = 0;
};


class PtexTexture {
 protected:
    virtual ~PtexTexture() {}

 public:
    PTEXAPI static PtexTexture* open(const char* path, Ptex::String& error, bool premultiply=0);


    virtual void release() = 0;

    virtual const char* path() = 0;

    struct Info {
        MeshType meshType;
        DataType dataType;
        BorderMode uBorderMode;
        BorderMode vBorderMode;
        EdgeFilterMode edgeFilterMode;
        int alphaChannel;
        int numChannels;
        int numFaces;
    };
    virtual Info getInfo() = 0;

    virtual Ptex::MeshType meshType() = 0;

    virtual Ptex::DataType dataType() = 0;

    virtual Ptex::BorderMode uBorderMode() = 0;

    virtual Ptex::BorderMode vBorderMode() = 0;

    virtual Ptex::EdgeFilterMode edgeFilterMode() = 0;

    virtual int alphaChannel() = 0;

    virtual int numChannels() = 0;

    virtual int numFaces() = 0;

    virtual bool hasEdits() = 0;

    virtual bool hasMipMaps() = 0;

    virtual PtexMetaData* getMetaData() = 0;

    virtual const Ptex::FaceInfo& getFaceInfo(int faceid) = 0;

    virtual void getData(int faceid, void* buffer, int stride) = 0;

    virtual void getData(int faceid, void* buffer, int stride, Ptex::Res res) = 0;

    virtual PtexFaceData* getData(int faceid) = 0;

    virtual PtexFaceData* getData(int faceid, Ptex::Res res) = 0;

    virtual void getPixel(int faceid, int u, int v,
                          float* result, int firstchan, int nchannels) = 0;

    virtual void getPixel(int faceid, int u, int v,
                          float* result, int firstchan, int nchannels,
                          Ptex::Res res) = 0;

    virtual void* getConstantData(int faceid) = 0;
};


class PtexInputHandler {
 protected:
    virtual ~PtexInputHandler() {}

 public:
    typedef void* Handle;

    virtual Handle open(const char* path) = 0;

    virtual void seek(Handle handle, int64_t pos) = 0;

    virtual size_t read(void* buffer, size_t size, Handle handle) = 0;

    virtual bool close(Handle handle) = 0;

    virtual const char* lastError() = 0;
};


class PtexErrorHandler {
 protected:
    virtual ~PtexErrorHandler() {}

 public:
    virtual void reportError(const char* error) = 0;
};


class PtexCache {
 protected:
    virtual ~PtexCache() {}

 public:
    PTEXAPI static PtexCache* create(int maxFiles,
                                     size_t maxMem,
                                     bool premultiply=false,
                                     PtexInputHandler* inputHandler=0,
                                     PtexErrorHandler* errorHandler=0);

    virtual void release() = 0;

    virtual void setSearchPath(const char* path) = 0;

    virtual const char* getSearchPath() = 0;

    virtual PtexTexture* get(const char* path, Ptex::String& error) = 0;

    virtual void purge(PtexTexture* texture) = 0;

    virtual void purge(const char* path) = 0;

    virtual void purgeAll() = 0;

    struct Stats {
        uint64_t memUsed;
        uint64_t peakMemUsed;
        uint64_t filesOpen;
        uint64_t peakFilesOpen;
        uint64_t filesAccessed;
        uint64_t fileReopens;
        uint64_t blockReads;
    };

    virtual void getStats(Stats& stats) = 0;
};


class PtexWriter {
 protected:
    virtual ~PtexWriter() {}

 public:
    PTEXAPI
    static PtexWriter* open(const char* path,
                            Ptex::MeshType mt, Ptex::DataType dt,
                            int nchannels, int alphachan, int nfaces,
                            Ptex::String& error, bool genmipmaps=true);

    PTEXAPI
    static PtexWriter* edit(const char* path,
                            Ptex::MeshType mt, Ptex::DataType dt,
                            int nchannels, int alphachan, int nfaces,
                            Ptex::String& error, bool genmipmaps=true);

    PTEXAPI
    static PtexWriter* edit(const char* path, bool incremental,
                            Ptex::MeshType mt, Ptex::DataType dt,
                            int nchannels, int alphachan, int nfaces,
                            Ptex::String& error, bool genmipmaps=true);

    PTEXAPI
    static bool applyEdits(const char* path, Ptex::String& error);

    virtual void release() = 0;

    virtual void setBorderModes(Ptex::BorderMode uBorderMode, Ptex::BorderMode vBorderMode) = 0;

    virtual void setEdgeFilterMode(Ptex::EdgeFilterMode edgeFilterMode) = 0;

    virtual void writeMeta(const char* key, const char* string) = 0;

    virtual void writeMeta(const char* key, const int8_t* value, int count) = 0;

    virtual void writeMeta(const char* key, const int16_t* value, int count) = 0;

    virtual void writeMeta(const char* key, const int32_t* value, int count) = 0;

    virtual void writeMeta(const char* key, const float* value, int count) = 0;

    virtual void writeMeta(const char* key, const double* value, int count) = 0;

    virtual void writeMeta(PtexMetaData* data) = 0;

    virtual bool writeFace(int faceid, const Ptex::FaceInfo& info, const void* data, int stride=0) = 0;

    virtual bool writeConstantFace(int faceid, const Ptex::FaceInfo& info, const void* data) = 0;

    virtual bool close(Ptex::String& error) = 0;

#if NEW_API
    virtual bool writeFaceReduction(int faceid, const Ptex::Res& res, const void* data, int stride=0) = 0;
    virtual bool writeConstantFaceReduction(int faceid, const Ptex::Res& res, const void* data) = 0;
#endif
};


class PtexFilter {
 protected:
    virtual ~PtexFilter() {}

 public:
    enum FilterType {
        f_point,                
        f_bilinear,             
        f_box,                  
        f_gaussian,             
        f_bicubic,              
        f_bspline,              
        f_catmullrom,           
        f_mitchell              
    };

    struct Options {
        int __structSize;       
        FilterType filter;      
        bool lerp;              
        float sharpness;        
        bool noedgeblend;       

        Options(FilterType filter_=f_box, bool lerp_=0, float sharpness_=0, bool noedgeblend_=0) :
            __structSize(sizeof(Options)),
            filter(filter_), lerp(lerp_), sharpness(sharpness_), noedgeblend(noedgeblend_) {}
    };


    /* Evaluate a texture using specified filter options

        The filter region is a parallelogram centered at the given
        (u,v) coordinate with sides defined by two vectors [uw1, vw1]
        and [uw2, vw2].  For an axis-aligned rectangle, the vectors
        are [uw, 0] and [0, vw].  See \link filterfootprint Filter
        Footprint \endlink for details.

        @param tx Texture to evaluate
        @param opts Filter options
        @param result Buffer to hold filter result.  Must be large enough to hold nchannels worth of data.
        @param firstchan First channel to evaluate [0..tx->numChannels()-1]
        @param nchannels Number of channels to evaluate
        @param faceid Face index [0..tx->numFaces()-1]
        @param u U coordinate, normalized [0..1]
        @param v V coordinate, normalized [0..1]
        @param uw1 U filter width 1, normalized [0..1]
        @param vw1 V filter width 1, normalized [0..1]
        @param uw2 U filter width 2, normalized [0..1]
        @param vw2 V filter width 2, normalized [0..1]
        @param width scale factor for filter width
        @param blur amount to add to filter width [0..1]
    */
    PTEXAPI static void eval(PtexTexture* tx, const Options& opts,
                             float* result, int firstchan, int nchannels,
                             int faceid, float u, float v, float uw1, float vw1, float uw2, float vw2,
                             float width=1, float blur=0);

    /* Construct a filter for the given texture. Deprecated. (use static eval method)
    */
    PTEXAPI static PtexFilter* getFilter(PtexTexture* tx, const Options& opts);

    virtual void release() = 0;

    virtual void eval(float* result, int firstchan, int nchannels,
                      int faceid, float u, float v, float uw1, float vw1, float uw2, float vw2,
                      float width=1, float blur=0) = 0;
};


template <class T> class PtexPtr {
    T* _ptr;
 public:
    PtexPtr(T* ptr=0) : _ptr(ptr) {}

    ~PtexPtr() { if (_ptr) _ptr->release(); }

    operator T* () const { return _ptr; }

    T* operator-> () const { return _ptr; }

    T* get() const { return _ptr; }

    void swap(PtexPtr& p)
    {
        T* tmp = p._ptr;
        p._ptr = _ptr;
        _ptr = tmp;
    }

    void reset(T* ptr=0) {
        if (_ptr) _ptr->release();
        _ptr = ptr;
    }

 private:
    PtexPtr(const PtexPtr& p);

    void operator= (PtexPtr& p);
};

#ifndef DOXYGEN
namespace PtexUtils {}

PTEX_NAMESPACE_END

using Ptex::PtexMetaData;
using Ptex::PtexFaceData;
using Ptex::PtexTexture;
using Ptex::PtexInputHandler;
using Ptex::PtexErrorHandler;
using Ptex::PtexCache;
using Ptex::PtexWriter;
using Ptex::PtexFilter;
using Ptex::PtexPtr;
namespace PtexUtils = Ptex::PtexUtils;

#endif
#endif