PageRenderTime 152ms CodeModel.GetById 82ms app.highlight 60ms RepoModel.GetById 1ms app.codeStats 1ms

/export/OpenColorIO/OpenColorIO.h

http://github.com/imageworks/OpenColorIO
C++ Header | 1268 lines | 396 code | 226 blank | 646 comment | 0 complexity | 7283137c7876cf1e5fcab7c3a2ec20d5 MD5 | raw file
   1/*
   2Copyright (c) 2003-2010 Sony Pictures Imageworks Inc., et al.
   3All Rights Reserved.
   4
   5Redistribution and use in source and binary forms, with or without
   6modification, are permitted provided that the following conditions are
   7met:
   8* Redistributions of source code must retain the above copyright
   9  notice, this list of conditions and the following disclaimer.
  10* Redistributions in binary form must reproduce the above copyright
  11  notice, this list of conditions and the following disclaimer in the
  12  documentation and/or other materials provided with the distribution.
  13* Neither the name of Sony Pictures Imageworks nor the names of its
  14  contributors may be used to endorse or promote products derived from
  15  this software without specific prior written permission.
  16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27*/
  28
  29
  30#ifndef INCLUDED_OCIO_OPENCOLORIO_H
  31#define INCLUDED_OCIO_OPENCOLORIO_H
  32
  33#include <exception>
  34#include <iosfwd>
  35#include <string>
  36#include <cstddef>
  37
  38#include "OpenColorABI.h"
  39#include "OpenColorTypes.h"
  40#include "OpenColorTransforms.h"
  41
  42/*!rst::
  43C++ API
  44=======
  45
  46**Usage Example:** *Compositing plugin that converts from "log" to "lin"*
  47
  48.. code-block:: cpp
  49   
  50   #include <OpenColorIO/OpenColorIO.h>
  51   namespace OCIO = OCIO_NAMESPACE;
  52   
  53   try
  54   {
  55       // Get the global OpenColorIO config
  56       // This will auto-initialize (using $OCIO) on first use
  57       OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
  58       
  59       // Get the processor corresponding to this transform.
  60       OCIO::ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_COMPOSITING_LOG,
  61                                                                  OCIO::ROLE_SCENE_LINEAR);
  62    
  63       // Wrap the image in a light-weight ImageDescription
  64       OCIO::PackedImageDesc img(imageData, w, h, 4);
  65       
  66       // Apply the color transformation (in place)
  67       processor->apply(img);
  68   }
  69   catch(OCIO::Exception & exception)
  70   {
  71       std::cerr << "OpenColorIO Error: " << exception.what() << std::endl;
  72   }
  73
  74*/
  75
  76OCIO_NAMESPACE_ENTER
  77{
  78    ///////////////////////////////////////////////////////////////////////////
  79    //!rst::
  80    // Exceptions
  81    // **********
  82    
  83    //!cpp:class:: An exception class to throw for errors detected at
  84    // runtime.
  85    //
  86    // .. warning:: 
  87    //    All functions in the Config class can potentially throw this exception.
  88    class OCIOEXPORT Exception : public std::exception
  89    {
  90    public:
  91        //!cpp:function:: Constructor that takes a string as the exception message.
  92        Exception(const char *) throw();
  93        //!cpp:function:: Constructor that takes an exception pointer.
  94        Exception(const Exception&) throw();
  95        //!cpp:function:: Constructor that takes an exception pointer and returns an exception pointer (???).
  96        Exception& operator=(const Exception&) throw();
  97        //!cpp:function::
  98        virtual ~Exception() throw();
  99        //!cpp:function::
 100        virtual const char* what() const throw();
 101        
 102    private:
 103        std::string msg_;
 104    };
 105    
 106    //!cpp:class:: An exception class for errors detected at
 107    // runtime, thrown when OCIO cannot find a file that is expected to
 108    // exist. This is provided as a custom type to
 109    // distinguish cases where one wants to continue looking for
 110    // missing files, but wants to properly fail
 111    // for other error conditions.
 112    
 113    class OCIOEXPORT ExceptionMissingFile : public Exception
 114    {
 115    public:
 116        //!cpp:function::
 117        ExceptionMissingFile(const char *) throw();
 118        //!cpp:function::
 119        ExceptionMissingFile(const ExceptionMissingFile&) throw();
 120    };
 121    
 122    ///////////////////////////////////////////////////////////////////////////
 123    //!rst::
 124    // Global
 125    // ******
 126    
 127    //!cpp:function::
 128    // OpenColorIO, during normal usage, tends to cache certain information
 129    // (such as the contents of LUTs on disk, intermediate results, etc.).
 130    // Calling this function will flush all such information.
 131    // Under normal usage, this is not necessary, but it can be helpful in particular instances,
 132    // such as designing OCIO profiles, and wanting to re-read luts without
 133    // restarting.
 134    
 135    extern OCIOEXPORT void ClearAllCaches();
 136    
 137    //!cpp:function:: Get the version number for the library, as a
 138    // dot-delimited string (e.g., "1.0.0"). This is also available
 139    // at compile time as OCIO_VERSION.
 140    
 141    extern OCIOEXPORT const char * GetVersion();
 142    
 143    //!cpp:function:: Get the version number for the library, as a
 144    // single 4-byte hex number (e.g., 0x01050200 for "1.5.2"), to be used
 145    // for numeric comparisons. This is also available
 146    // at compile time as OCIO_VERSION_HEX.
 147    
 148    extern OCIOEXPORT int GetVersionHex();
 149    
 150    //!cpp:function:: Get the global logging level.
 151    // You can override this at runtime using the :envvar:`OCIO_LOGGING_LEVEL`
 152    // environment variable. The client application that sets this should use
 153    // :cpp:func:`SetLoggingLevel`, and not the environment variable. The default value is INFO.
 154    
 155    extern OCIOEXPORT LoggingLevel GetLoggingLevel();
 156    
 157    //!cpp:function:: Set the global logging level.
 158    extern OCIOEXPORT void SetLoggingLevel(LoggingLevel level);
 159    
 160    
 161    ///////////////////////////////////////////////////////////////////////////
 162    //!rst::
 163    // Config
 164    // ******
 165    //
 166    // A config defines all the color spaces to be available at runtime.
 167    // 
 168    // The color configuration (:cpp:class:`Config`) is the main object for
 169    // interacting with this library. It encapsulates all of the information
 170    // necessary to use customized :cpp:class:`ColorSpaceTransform` and
 171    // :cpp:class:`DisplayTransform` operations.
 172    // 
 173    // See the :ref:`user-guide` for more information on
 174    // selecting, creating, and working with custom color configurations.
 175    // 
 176    // For applications interested in using only one color config at
 177    // a time (this is the vast majority of apps), their API would
 178    // traditionally get the global configuration and use that, as opposed to
 179    // creating a new one. This simplifies the use case for
 180    // plugins and bindings, as it alleviates the need to pass around configuration
 181    // handles.
 182    // 
 183    // An example of an application where this would not be sufficient would be
 184    // a multi-threaded image proxy server (daemon), which wished to handle
 185    // multiple show configurations in a single process concurrently. This
 186    // app would need to keep multiple configurations alive, and to manage them
 187    // appropriately.
 188    // 
 189    // Roughly speaking, a novice user should select a
 190    // default configuration that most closely approximates the use case
 191    // (animation, visual effects, etc.), and set the :envvar:`OCIO` environment
 192    // variable to point at the root of that configuration.
 193    // 
 194    // .. note::
 195    //    Initialization using environment variables is typically preferable in
 196    //    a multi-app ecosystem, as it allows all applications to be
 197    //    consistently configured.
 198    //
 199    // See :ref:`developers-usageexamples`
 200    
 201    //!cpp:function:: Get the current configuration.
 202    
 203    extern OCIOEXPORT ConstConfigRcPtr GetCurrentConfig();
 204    
 205    //!cpp:function:: Set the current configuration. This will then store a copy of the specified config.
 206    extern OCIOEXPORT void SetCurrentConfig(const ConstConfigRcPtr & config);
 207    
 208    
 209    //!cpp:class::
 210    class OCIOEXPORT Config
 211    {
 212    public:
 213        
 214        ///////////////////////////////////////////////////////////////////////////
 215        //!rst:: .. _cfginit_section:
 216        // 
 217        // Initialization
 218        // ^^^^^^^^^^^^^^
 219        
 220        //!cpp:function:: Constructor...ELABORATE
 221        static ConfigRcPtr Create();
 222        //!cpp:function:: 
 223        static ConstConfigRcPtr CreateFromEnv();
 224        //!cpp:function::
 225        static ConstConfigRcPtr CreateFromFile(const char * filename);
 226        //!cpp:function::
 227        static ConstConfigRcPtr CreateFromStream(std::istream & istream);
 228        
 229        //!cpp:function::
 230        ConfigRcPtr createEditableCopy() const;
 231        
 232        //!cpp:function::
 233        // This will throw an exception if the config is malformed. The most
 234        // common error occurs when references are made to colorspaces that do not
 235        // exist.
 236        void sanityCheck() const;
 237        
 238        //!cpp:function::
 239        const char * getDescription() const;
 240        //!cpp:function::
 241        void setDescription(const char * description);
 242        
 243        //!cpp:function::
 244        // Returns the string representation of the Config in YAML text form.
 245        // This is typically stored on disk in a file with the extension .ocio.
 246        void serialize(std::ostream & os) const;
 247        
 248        //!cpp:function::
 249        // This will produce a hash of the all colorspace definitions, etc.
 250        // All external references, such as files used in FileTransforms, etc.,
 251        // will be incorporated into the cacheID. While the contents of
 252        // the files are not read, the file system is queried for relavent
 253        // information (mtime, inode) so that the config's cacheID will
 254        // change when the underlying luts are updated.
 255        // If a context is not provided, the current Context will be used.
 256        // If a null context is provided, file references will not be taken into
 257        // account (this is essentially a hash of Config::serialize).
 258        const char * getCacheID() const;
 259        //!cpp:function::
 260        const char * getCacheID(const ConstContextRcPtr & context) const;
 261        
 262        ///////////////////////////////////////////////////////////////////////////
 263        //!rst:: .. _cfgresource_section:
 264        // 
 265        // Resources
 266        // ^^^^^^^^^
 267        // Given a lut src name, where should we find it?
 268        
 269        //!cpp:function::
 270        ConstContextRcPtr getCurrentContext() const;
 271        
 272        //!cpp:function::
 273        void addEnvironmentVar(const char * name, const char * defaultValue);
 274        //!cpp:function::
 275        int getNumEnvironmentVars() const;
 276        //!cpp:function::
 277        const char * getEnvironmentVarNameByIndex(int index) const;
 278        //!cpp:function::
 279        const char * getEnvironmentVarDefault(const char * name) const;
 280        //!cpp:function::
 281        void clearEnvironmentVars();
 282        //!cpp:function::
 283        void setEnvironmentMode(EnvironmentMode mode);
 284        //!cpp:function::
 285        EnvironmentMode getEnvironmentMode() const;
 286        //!cpp:function::
 287        void loadEnvironment();
 288        
 289        //!cpp:function::
 290        const char * getSearchPath() const;
 291        //!cpp:function::
 292        void setSearchPath(const char * path);
 293        
 294        //!cpp:function::
 295        const char * getWorkingDir() const;
 296        //!cpp:function::
 297        void setWorkingDir(const char * dirname);
 298        
 299        ///////////////////////////////////////////////////////////////////////////
 300        //!rst:: .. _cfgcolorspaces_section:
 301        // 
 302        // ColorSpaces
 303        // ^^^^^^^^^^^
 304        
 305        //!cpp:function::
 306        int getNumColorSpaces() const;
 307        //!cpp:function:: This will null if an invalid index is specified
 308        const char * getColorSpaceNameByIndex(int index) const;
 309        
 310        //!rst::
 311        // .. note::
 312        //    These fcns all accept either a color space OR role name.
 313        //    (Colorspace names take precedence over roles.)
 314        
 315        //!cpp:function:: This will return null if the specified name is not
 316        // found.
 317        ConstColorSpaceRcPtr getColorSpace(const char * name) const;
 318        //!cpp:function::
 319        int getIndexForColorSpace(const char * name) const;
 320        
 321        //!cpp:function::
 322        // .. note::
 323        //    If another color space is already registered with the same name,
 324        //    this will overwrite it. This stores a copy of the specified
 325        //    color space.
 326        void addColorSpace(const ConstColorSpaceRcPtr & cs);
 327        //!cpp:function::
 328        void clearColorSpaces();
 329        
 330        //!cpp:function:: Given the specified string, get the longest,
 331        // right-most, colorspace substring that appears.
 332        //
 333        // * If strict parsing is enabled, and no color space is found, return
 334        //   an empty string.
 335        // * If strict parsing is disabled, return ROLE_DEFAULT (if defined).
 336        // * If the default role is not defined, return an empty string.
 337        const char * parseColorSpaceFromString(const char * str) const;
 338        
 339        //!cpp:function::
 340        bool isStrictParsingEnabled() const;
 341        //!cpp:function::
 342        void setStrictParsingEnabled(bool enabled);
 343        
 344        ///////////////////////////////////////////////////////////////////////////
 345        //!rst:: .. _cfgroles_section:
 346        // 
 347        // Roles
 348        // ^^^^^
 349        // A role is like an alias for a colorspace. You can query the colorspace
 350        // corresponding to a role using the normal getColorSpace fcn.
 351        
 352        //!cpp:function::
 353        // .. note::
 354        //    Setting the ``colorSpaceName`` name to a null string unsets it.
 355        void setRole(const char * role, const char * colorSpaceName);
 356        //!cpp:function::
 357        int getNumRoles() const;
 358        //!cpp:function:: Return true if the role has been defined.
 359        bool hasRole(const char * role) const;
 360        //!cpp:function:: Get the role name at index, this will return values
 361        // like 'scene_linear', 'compositing_log'.
 362        // Return empty string if index is out of range.
 363        const char * getRoleName(int index) const;
 364        
 365        
 366        
 367        ///////////////////////////////////////////////////////////////////////////
 368        //!rst:: .. _cfgdisplayview_section:
 369        // 
 370        // Display/View Registration
 371        // ^^^^^^^^^^^^^^^^^^^^^^^^^
 372        //
 373        // Looks is a potentially comma (or colon) delimited list of lookNames,
 374        // Where +/- prefixes are optionally allowed to denote forward/inverse
 375        // look specification. (And forward is assumed in the absense of either)
 376        
 377        //!cpp:function::
 378        const char * getDefaultDisplay() const;
 379        //!cpp:function::
 380        int getNumDisplays() const;
 381        //!cpp:function::
 382        const char * getDisplay(int index) const;
 383        
 384        //!cpp:function::
 385        const char * getDefaultView(const char * display) const;
 386        //!cpp:function::
 387        int getNumViews(const char * display) const;
 388        //!cpp:function::
 389        const char * getView(const char * display, int index) const;
 390        
 391        //!cpp:function::
 392        const char * getDisplayColorSpaceName(const char * display, const char * view) const;
 393        //!cpp:function::
 394        const char * getDisplayLooks(const char * display, const char * view) const;
 395        
 396        //!cpp:function:: For the (display,view) combination,
 397        // specify which colorSpace and look to use.
 398        // If a look is not desired, then just pass an empty string
 399        
 400        void addDisplay(const char * display, const char * view,
 401                        const char * colorSpaceName, const char * looks);
 402        
 403        //!cpp:function::
 404        void clearDisplays();
 405        
 406        // $OCIO_ACTIVE_DISPLAYS envvar can, at runtime, optionally override the allowed displays.
 407        // It is a comma or colon delimited list.
 408        // Active displays that are not in the specified profile will be ignored, and the
 409        // left-most defined display will be the default.
 410        
 411        //!cpp:function:: Comma-delimited list of display names.
 412        void setActiveDisplays(const char * displays);
 413        //!cpp:function::
 414        const char * getActiveDisplays() const;
 415        
 416        // $OCIO_ACTIVE_VIEWS envvar can, at runtime, optionally override the allowed views.
 417        // It is a comma or colon delimited list.
 418        // Active views that are not in the specified profile will be ignored, and the
 419        // left-most defined view will be the default.
 420        
 421        //!cpp:function:: Comma-delimited list of view names.
 422        void setActiveViews(const char * views);
 423        //!cpp:function::
 424        const char * getActiveViews() const;
 425        
 426        
 427        ///////////////////////////////////////////////////////////////////////////
 428        //!rst:: .. _cfgluma_section:
 429        // 
 430        // Luma
 431        // ^^^^
 432        //
 433        // Get the default coefficients for computing luma.
 434        //
 435        // .. note::
 436        //    There is no "1 size fits all" set of luma coefficients. (The
 437        //    values are typically different for each colorspace, and the
 438        //    application of them may be nonsensical depending on the
 439        //    intensity coding anyways). Thus, the 'right' answer is to make
 440        //    these functions on the :cpp:class:`Config` class. However, it's
 441        //    often useful to have a config-wide default so here it is. We will
 442        //    add the colorspace specific luma call if/when another client is
 443        //    interesting in using it.
 444        
 445        //!cpp:function::
 446        void getDefaultLumaCoefs(float * rgb) const;
 447        //!cpp:function:: These should be normalized (sum to 1.0 exactly).
 448        void setDefaultLumaCoefs(const float * rgb);
 449        
 450        
 451        ///////////////////////////////////////////////////////////////////////////
 452        //!rst:: .. _cflooka_section:
 453        // 
 454        // Look
 455        // ^^^^
 456        //
 457        // Manager per-shot look settings.
 458        //
 459        
 460        //!cpp:function::
 461        ConstLookRcPtr getLook(const char * name) const;
 462        
 463        //!cpp:function::
 464        int getNumLooks() const;
 465        
 466        //!cpp:function::
 467        const char * getLookNameByIndex(int index) const;
 468        
 469        //!cpp:function::
 470        void addLook(const ConstLookRcPtr & look);
 471        
 472        //!cpp:function::
 473        void clearLooks();
 474        
 475        
 476        ///////////////////////////////////////////////////////////////////////////
 477        //!rst:: .. _cfgprocessors_section:
 478        // 
 479        // Processors
 480        // ^^^^^^^^^^
 481        //
 482        // Convert from inputColorSpace to outputColorSpace
 483        // 
 484        // .. note::
 485        //    This may provide higher fidelity than anticipated due to internal
 486        //    optimizations. For example, if the inputcolorspace and the
 487        //    outputColorSpace are members of the same family, no conversion
 488        //    will be applied, even though strictly speaking quantization
 489        //    should be added.
 490        // 
 491        // If you wish to test these calls for quantization characteristics,
 492        // apply in two steps; the image must contain RGB triples (though
 493        // arbitrary numbers of additional channels can be supported (ignored)
 494        // using the pixelStrideBytes arg).
 495        
 496        //!cpp:function::
 497        ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
 498                                         const ConstColorSpaceRcPtr & srcColorSpace,
 499                                         const ConstColorSpaceRcPtr & dstColorSpace) const;
 500        //!cpp:function::
 501        ConstProcessorRcPtr getProcessor(const ConstColorSpaceRcPtr & srcColorSpace,
 502                                         const ConstColorSpaceRcPtr & dstColorSpace) const;
 503        
 504            //!cpp:function::
 505        // .. note::
 506        //    Names can be colorspace name, role name, or a combination of both.
 507        ConstProcessorRcPtr getProcessor(const char * srcName,
 508                                         const char * dstName) const;
 509        //!cpp:function::
 510        ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
 511                                         const char * srcName,
 512                                         const char * dstName) const;
 513        
 514        //!rst:: Get the processor for the specified transform.
 515        //
 516        // Not often needed, but will allow for the re-use of atomic OCIO
 517        // functionality (such as to apply an individual LUT file).
 518        
 519        //!cpp:function::
 520        ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr& transform) const;
 521        //!cpp:function::
 522        ConstProcessorRcPtr getProcessor(const ConstTransformRcPtr& transform,
 523                                         TransformDirection direction) const;
 524        //!cpp:function::
 525        ConstProcessorRcPtr getProcessor(const ConstContextRcPtr & context,
 526                                         const ConstTransformRcPtr& transform,
 527                                         TransformDirection direction) const;
 528        
 529    private:
 530        Config();
 531        ~Config();
 532        
 533        Config(const Config &);
 534        Config& operator= (const Config &);
 535        
 536        static void deleter(Config* c);
 537        
 538        class Impl;
 539        friend class Impl;
 540        Impl * m_impl;
 541        Impl * getImpl() { return m_impl; }
 542        const Impl * getImpl() const { return m_impl; }
 543    };
 544    
 545    extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Config&);
 546    
 547    
 548    ///////////////////////////////////////////////////////////////////////////
 549    //!rst:: .. _colorspace_section:
 550    // 
 551    // ColorSpace
 552    // **********
 553    // The *ColorSpace* is the state of an image with respect to colorimetry
 554    // and color encoding. Transforming images between different
 555    // *ColorSpaces* is the primary motivation for this library.
 556    //
 557    // While a complete discussion of colorspaces is beyond the scope of
 558    // header documentation, traditional uses would be to have *ColorSpaces*
 559    // corresponding to: physical capture devices (known cameras, scanners),
 560    // and internal 'convenience' spaces (such as scene linear, logarithmic).
 561    //
 562    // *ColorSpaces* are specific to a particular image precision (float32,
 563    // uint8, etc.), and the set of ColorSpaces that provide equivalent mappings
 564    // (at different precisions) are referred to as a 'family'.
 565    
 566    //!cpp:class::
 567    class OCIOEXPORT ColorSpace
 568    {
 569    public:
 570        //!cpp:function::
 571        static ColorSpaceRcPtr Create();
 572        
 573        //!cpp:function::
 574        ColorSpaceRcPtr createEditableCopy() const;
 575        
 576        //!cpp:function::
 577        const char * getName() const;
 578        //!cpp:function::
 579        void setName(const char * name);
 580        
 581        //!cpp:function::Get the family, for use in user interfaces (optional)
 582        const char * getFamily() const;
 583        //!cpp:function::Set the family, for use in user interfaces (optional)
 584        void setFamily(const char * family);
 585        
 586        //!cpp:function::Get the ColorSpace group name (used for equality comparisons)
 587        // This allows no-op transforms between different colorspaces.
 588        // If an equalityGroup is not defined (an empty string), it will be considered
 589        // unique (i.e., it will not compare as equal to other ColorSpaces with an
 590        // empty equality group).  This is often, though not always, set to the
 591        // same value as 'family'.
 592        const char * getEqualityGroup() const;
 593        //!cpp:function::
 594        void setEqualityGroup(const char * equalityGroup);
 595        
 596        //!cpp:function::
 597        const char * getDescription() const;
 598        //!cpp:function::
 599        void setDescription(const char * description);
 600        
 601        //!cpp:function::
 602        BitDepth getBitDepth() const;
 603        //!cpp:function::
 604        void setBitDepth(BitDepth bitDepth);
 605        
 606        ///////////////////////////////////////////////////////////////////////////
 607        //!rst::
 608        // Data
 609        // ^^^^
 610        // ColorSpaces that are data are treated a bit special. Basically, any
 611        // colorspace transforms you try to apply to them are ignored. (Think
 612        // of applying a gamut mapping transform to an ID pass). Also, the
 613        // :cpp:class:`DisplayTransform` process obeys special 'data min' and
 614        // 'data max' args.
 615        //
 616        // This is traditionally used for pixel data that represents non-color
 617        // pixel data, such as normals, point positions, ID information, etc.
 618        
 619        //!cpp:function::
 620        bool isData() const;
 621        //!cpp:function::
 622        void setIsData(bool isData);
 623        
 624        ///////////////////////////////////////////////////////////////////////////
 625        //!rst::
 626        // Allocation
 627        // ^^^^^^^^^^
 628        // If this colorspace needs to be transferred to a limited dynamic
 629        // range coding space (such as during display with a GPU path), use this
 630        // allocation to maximize bit efficiency.
 631        
 632        //!cpp:function::
 633        Allocation getAllocation() const;
 634        //!cpp:function::
 635        void setAllocation(Allocation allocation);
 636        
 637        //!rst::
 638        // Specify the optional variable values to configure the allocation.
 639        // If no variables are specified, the defaults are used.
 640        //
 641        // ALLOCATION_UNIFORM::
 642        //    
 643        //    2 vars: [min, max]
 644        //
 645        // ALLOCATION_LG2::
 646        //    
 647        //    2 vars: [lg2min, lg2max]
 648        //    3 vars: [lg2min, lg2max, linear_offset]
 649        
 650        //!cpp:function::
 651        int getAllocationNumVars() const;
 652        //!cpp:function::
 653        void getAllocationVars(float * vars) const;
 654        //!cpp:function::
 655        void setAllocationVars(int numvars, const float * vars);
 656        
 657        ///////////////////////////////////////////////////////////////////////////
 658        //!rst::
 659        // Transform
 660        // ^^^^^^^^^
 661        
 662        //!cpp:function::
 663        // If a transform in the specified direction has been specified,
 664        // return it. Otherwise return a null ConstTransformRcPtr
 665        ConstTransformRcPtr getTransform(ColorSpaceDirection dir) const;
 666        //!cpp:function::
 667        // Specify the transform for the appropriate direction.
 668        // Setting the transform to null will clear it.
 669        void setTransform(const ConstTransformRcPtr & transform,
 670                          ColorSpaceDirection dir);
 671    
 672    private:
 673        ColorSpace();
 674        ~ColorSpace();
 675        
 676        ColorSpace(const ColorSpace &);
 677        ColorSpace& operator= (const ColorSpace &);
 678        
 679        static void deleter(ColorSpace* c);
 680        
 681        class Impl;
 682        friend class Impl;
 683        Impl * m_impl;
 684        Impl * getImpl() { return m_impl; }
 685        const Impl * getImpl() const { return m_impl; }
 686    };
 687    
 688    extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ColorSpace&);
 689    
 690    
 691    
 692    
 693    
 694    
 695    
 696    ///////////////////////////////////////////////////////////////////////////
 697    //!rst:: .. _look_section:
 698    // 
 699    // Look
 700    // ****
 701    // The *Look* is an 'artistic' image modification, in a specified image
 702    // state.
 703    // The processSpace defines the ColorSpace the image is required to be
 704    // in, for the math to apply correctly.
 705    
 706    //!cpp:class::
 707    class OCIOEXPORT Look
 708    {
 709    public:
 710        //!cpp:function::
 711        static LookRcPtr Create();
 712        
 713        //!cpp:function::
 714        LookRcPtr createEditableCopy() const;
 715        
 716        //!cpp:function::
 717        const char * getName() const;
 718        //!cpp:function::
 719        void setName(const char * name);
 720        
 721        //!cpp:function::
 722        const char * getProcessSpace() const;
 723        //!cpp:function::
 724        void setProcessSpace(const char * processSpace);
 725        
 726        //!cpp:function::
 727        ConstTransformRcPtr getTransform() const;
 728        //!cpp:function:: Setting a transform to a non-null call makes it allowed.
 729        void setTransform(const ConstTransformRcPtr & transform);
 730        
 731        //!cpp:function::
 732        ConstTransformRcPtr getInverseTransform() const;
 733        //!cpp:function:: Setting a transform to a non-null call makes it allowed.
 734        void setInverseTransform(const ConstTransformRcPtr & transform);
 735    private:
 736        Look();
 737        ~Look();
 738        
 739        Look(const Look &);
 740        Look& operator= (const Look &);
 741        
 742        static void deleter(Look* c);
 743        
 744        class Impl;
 745        friend class Impl;
 746        Impl * m_impl;
 747        Impl * getImpl() { return m_impl; }
 748        const Impl * getImpl() const { return m_impl; }
 749    };
 750    
 751    extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Look&);
 752    
 753    
 754    ///////////////////////////////////////////////////////////////////////////
 755    //!rst::
 756    // Processor
 757    // *********
 758    
 759    //!cpp:class::
 760    class OCIOEXPORT Processor
 761    {
 762    public:
 763        //!cpp:function::
 764        static ProcessorRcPtr Create();
 765        
 766        //!cpp:function::
 767        bool isNoOp() const;
 768        
 769        //!cpp:function:: does the processor represent an image transformation that
 770        //                introduces crosstalk between the image channels
 771        bool hasChannelCrosstalk() const;
 772        
 773        //!cpp:function::
 774        ConstProcessorMetadataRcPtr getMetadata() const;
 775        
 776        ///////////////////////////////////////////////////////////////////////////
 777        //!rst::
 778        // CPU Path
 779        // ^^^^^^^^
 780        
 781        //!cpp:function:: Apply to an image.
 782        void apply(ImageDesc& img) const;
 783        
 784        //!rst::
 785        // Apply to a single pixel.
 786        // 
 787        // .. note::
 788        //    This is not as efficient as applying to an entire image at once.
 789        //    If you are processing multiple pixels, and have the flexibility,
 790        //    use the above function instead.
 791        
 792        //!cpp:function:: 
 793        void applyRGB(float * pixel) const;
 794        //!cpp:function:: 
 795        void applyRGBA(float * pixel) const;
 796        
 797        //!cpp:function:: 
 798        const char * getCpuCacheID() const;
 799        
 800        ///////////////////////////////////////////////////////////////////////////
 801        //!rst::
 802        // GPU Path
 803        // ^^^^^^^^
 804        // Get the 3d lut + cg shader for the specified
 805        // :cpp:class:`DisplayTransform`.
 806        //
 807        // cg signature will be::
 808        //    
 809        //    shaderFcnName(in half4 inPixel, const uniform sampler3D lut3d)
 810        //
 811        // lut3d should be size: 3 * edgeLen * edgeLen * edgeLen
 812        // return 0 if unknown
 813        
 814        //!cpp:function::
 815        const char * getGpuShaderText(const GpuShaderDesc & shaderDesc) const;
 816        //!cpp:function::
 817        const char * getGpuShaderTextCacheID(const GpuShaderDesc & shaderDesc) const;
 818        
 819        //!cpp:function::
 820        void getGpuLut3D(float* lut3d, const GpuShaderDesc & shaderDesc) const;
 821        //!cpp:function::
 822        const char * getGpuLut3DCacheID(const GpuShaderDesc & shaderDesc) const;
 823        
 824    private:
 825        Processor();
 826        ~Processor();
 827        
 828        Processor(const Processor &);
 829        Processor& operator= (const Processor &);
 830        
 831        static void deleter(Processor* c);
 832        
 833        friend class Config;
 834        
 835        class Impl;
 836        friend class Impl;
 837        Impl * m_impl;
 838        Impl * getImpl() { return m_impl; }
 839        const Impl * getImpl() const { return m_impl; }
 840    };
 841    
 842    
 843    //!cpp:class::
 844    // This class contains meta information about the process that generated
 845    // this processor.  The results of these functions do not
 846    // impact the pixel processing.
 847    
 848    class OCIOEXPORT ProcessorMetadata
 849    {
 850    public:
 851        //!cpp:function::
 852        static ProcessorMetadataRcPtr Create();
 853        
 854        //!cpp:function::
 855        int getNumFiles() const;
 856        //!cpp:function::
 857        const char * getFile(int index) const;
 858        
 859        //!cpp:function::
 860        int getNumLooks() const;
 861        //!cpp:function::
 862        const char * getLook(int index) const;
 863        
 864        //!cpp:function::
 865        void addFile(const char * fname);
 866        //!cpp:function::
 867        void addLook(const char * look);
 868    private:
 869        ProcessorMetadata();
 870        ~ProcessorMetadata();
 871        ProcessorMetadata(const ProcessorMetadata &);
 872        ProcessorMetadata& operator= (const ProcessorMetadata &);
 873        
 874        static void deleter(ProcessorMetadata* c);
 875        
 876        class Impl;
 877        friend class Impl;
 878        Impl * m_impl;
 879        Impl * getImpl() { return m_impl; }
 880        const Impl * getImpl() const { return m_impl; }
 881    };
 882    
 883    
 884    
 885    ///////////////////////////////////////////////////////////////////////////
 886    //!rst::
 887    // Baker
 888    // *****
 889    // 
 890    // In certain situations it is nessary to serilize transforms into a variety
 891    // of application specific lut formats. The Baker can be used to create lut
 892    // formats that ocio supports for writing.
 893    // 
 894    // **Usage Example:** *Bake a houdini sRGB viewer lut*
 895    // 
 896    // .. code-block:: cpp
 897    //    
 898    //    OCIO::ConstConfigRcPtr config = OCIO::Config::CreateFromEnv();
 899    //    OCIO::BakerRcPtr baker = OCIO::Baker::Create();
 900    //    baker->setConfig(config);
 901    //    baker->setFormat("houdini"); // set the houdini type
 902    //    baker->setType("3D"); // we want a 3D lut
 903    //    baker->setInputSpace("lnf");
 904    //    baker->setShaperSpace("log");
 905    //    baker->setTargetSpace("sRGB");
 906    //    std::ostringstream out;
 907    //    baker->bake(out); // fresh bread anyone!
 908    //    std::cout << out.str();
 909    
 910    class OCIOEXPORT Baker
 911    {
 912    public:
 913        //!cpp:function:: create a new Baker
 914        static BakerRcPtr Create();
 915        
 916        //!cpp:function:: create a copy of this Baker
 917        BakerRcPtr createEditableCopy() const;
 918        
 919        //!cpp:function:: set the config to use
 920        void setConfig(const ConstConfigRcPtr & config);
 921        //!cpp:function:: get the config to use
 922        ConstConfigRcPtr getConfig() const;
 923        
 924        //!cpp:function:: set the lut output format
 925        void setFormat(const char * formatName);
 926        //!cpp:function:: get the lut output format
 927        const char * getFormat() const;
 928        
 929        // TODO: Change this to an enum
 930        //!cpp:function:: set the lut output type (1D or 3D)
 931        void setType(const char * type);
 932        //!cpp:function:: get the lut output type
 933        const char * getType() const;
 934        
 935        //!cpp:function:: set *optional* meta data for luts that support it
 936        void setMetadata(const char * metadata);
 937        //!cpp:function:: get the meta data that has been set
 938        const char * getMetadata() const;
 939        
 940        //!cpp:function:: set the input ColorSpace that the lut will be
 941        // applied to
 942        void setInputSpace(const char * inputSpace);
 943        //!cpp:function:: get the input ColorSpace that has been set
 944        const char * getInputSpace() const;
 945        
 946        //!cpp:function:: set an *optional* ColorSpace to be used to shape /
 947        // transfer the input colorspace. This is mostly used to allocate
 948        // an HDR luminance range into an LDR one. If a shaper space
 949        // is not explicitly specified, and the file format supports one,
 950        // the ColorSpace Allocation will be used
 951        
 952        void setShaperSpace(const char * shaperSpace);
 953        //!cpp:function:: get the shaper colorspace that has been set
 954        const char * getShaperSpace() const;
 955
 956        //!cpp:function:: set the looks to be applied during baking
 957        // Looks is a potentially comma (or colon) delimited list of lookNames,
 958        // Where +/- prefixes are optionally allowed to denote forward/inverse
 959        // look specification. (And forward is assumed in the absense of either)
 960        void setLooks(const char * looks);
 961        //!cpp:function:: get the looks to be applied during baking
 962        const char * getLooks() const;
 963        
 964        //!cpp:function:: set the target device colorspace for the lut
 965        void setTargetSpace(const char * targetSpace);
 966        //!cpp:function:: get the target colorspace that has been set
 967        const char * getTargetSpace() const;
 968        
 969        //!cpp:function:: override the default the shaper sample size,
 970        // default: <format specific>
 971        void setShaperSize(int shapersize);
 972        //!cpp:function:: get the shaper sample size
 973        int getShaperSize() const;
 974        
 975        //!cpp:function:: override the default cube sample size
 976        // default: <format specific>
 977        void setCubeSize(int cubesize);
 978        //!cpp:function:: get the cube sample size
 979        int getCubeSize() const;
 980        
 981        //!cpp:function:: bake the lut into the output stream
 982        void bake(std::ostream & os) const;
 983        
 984        //!cpp:function:: get the number of lut writers
 985        static int getNumFormats();
 986        
 987        //!cpp:function:: get the lut writer at index, return empty string if
 988        // an invalid index is specified
 989        static const char * getFormatNameByIndex(int index);
 990        static const char * getFormatExtensionByIndex(int index);
 991        
 992    private:
 993        Baker();
 994        ~Baker();
 995        
 996        Baker(const Baker &);
 997        Baker& operator= (const Baker &);
 998        
 999        static void deleter(Baker* o);
1000        
1001        class Impl;
1002        friend class Impl;
1003        Impl * m_impl;
1004        Impl * getImpl() { return m_impl; }
1005        const Impl * getImpl() const { return m_impl; }
1006    };
1007    
1008    
1009    ///////////////////////////////////////////////////////////////////////////
1010    //!rst::
1011    // ImageDesc
1012    // *********
1013    
1014    //!rst::
1015    // .. c:var:: const ptrdiff_t AutoStride
1016    //    
1017    //    AutoStride
1018    const ptrdiff_t AutoStride = std::numeric_limits<ptrdiff_t>::min();
1019    
1020    //!cpp:class::
1021    // This is a light-weight wrapper around an image, that provides a context
1022    // for pixel access. This does NOT claim ownership of the pixels or copy
1023    // image data
1024    
1025    class OCIOEXPORT ImageDesc
1026    {
1027    public:
1028        //!cpp:function::
1029        virtual ~ImageDesc();
1030    private:
1031        ImageDesc& operator= (const ImageDesc &);
1032    };
1033    
1034    extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const ImageDesc&);
1035    
1036    
1037    ///////////////////////////////////////////////////////////////////////////
1038    //!rst::
1039    // PackedImageDesc
1040    // ^^^^^^^^^^^^^^^
1041    
1042    //!cpp:class::
1043    class OCIOEXPORT PackedImageDesc : public ImageDesc
1044    {
1045    public:
1046        //!cpp:function::
1047        // Pass the pointer to packed image data: rgbrgbrgb, etc.
1048        // The number of channels must be greater than or equal to 3
1049        // If a 4th channel is specified, it is assumed to be alpha
1050        // information.  Channels > 4 will be ignored.
1051        
1052        PackedImageDesc(float * data,
1053                        long width, long height,
1054                        long numChannels,
1055                        ptrdiff_t chanStrideBytes = AutoStride,
1056                        ptrdiff_t xStrideBytes = AutoStride,
1057                        ptrdiff_t yStrideBytes = AutoStride);
1058        //!cpp:function::
1059        virtual ~PackedImageDesc();
1060        
1061        //!cpp:function::
1062        float * getData() const;
1063        
1064        //!cpp:function::
1065        long getWidth() const;
1066        //!cpp:function::
1067        long getHeight() const;
1068        //!cpp:function::
1069        long getNumChannels() const;
1070        
1071        //!cpp:function::
1072        ptrdiff_t getChanStrideBytes() const;
1073        //!cpp:function::
1074        ptrdiff_t getXStrideBytes() const;
1075        //!cpp:function::
1076        ptrdiff_t getYStrideBytes() const;
1077        
1078    private:
1079        class Impl;
1080        friend class Impl;
1081        Impl * m_impl;
1082        Impl * getImpl() { return m_impl; }
1083        const Impl * getImpl() const { return m_impl; }
1084        
1085        PackedImageDesc(const PackedImageDesc &);
1086        PackedImageDesc& operator= (const PackedImageDesc &);
1087    };
1088    
1089    
1090    ///////////////////////////////////////////////////////////////////////////
1091    //!rst::
1092    // PlanarImageDesc
1093    // ^^^^^^^^^^^^^^^
1094    
1095    //!cpp:class::
1096    class OCIOEXPORT PlanarImageDesc : public ImageDesc
1097    {
1098    public:
1099        //!cpp:function::
1100        // Pass the pointer to the specified image planes: rrrr gggg bbbb, etc.
1101        // aData is optional, pass NULL if no alpha exists.
1102        // {r,g,b} Data must be specified
1103        
1104        PlanarImageDesc(float * rData, float * gData, float * bData, float * aData,
1105                        long width, long height,
1106                        ptrdiff_t yStrideBytes = AutoStride);
1107        //!cpp:function::
1108        virtual ~PlanarImageDesc();
1109        
1110        //!cpp:function::
1111        float* getRData() const;
1112        //!cpp:function::
1113        float* getGData() const;
1114        //!cpp:function::
1115        float* getBData() const;
1116        //!cpp:function::
1117        float* getAData() const;
1118        
1119        //!cpp:function::
1120        long getWidth() const;
1121        //!cpp:function::
1122        long getHeight() const;
1123        
1124        //!cpp:function::
1125        ptrdiff_t getYStrideBytes() const;
1126        
1127    private:
1128        class Impl;
1129        friend class Impl;
1130        Impl * m_impl;
1131        Impl * getImpl() { return m_impl; }
1132        const Impl * getImpl() const { return m_impl; }
1133        
1134        PlanarImageDesc(const PlanarImageDesc &);
1135        PlanarImageDesc& operator= (const PlanarImageDesc &);
1136    };
1137    
1138    
1139    ///////////////////////////////////////////////////////////////////////////
1140    //!rst::
1141    // GpuShaderDesc
1142    // *************
1143    
1144    //!cpp:class::
1145    class OCIOEXPORT GpuShaderDesc
1146    {
1147    public:
1148        //!cpp:function::
1149        GpuShaderDesc();
1150        //!cpp:function::
1151        ~GpuShaderDesc();
1152        
1153        //!cpp:function::
1154        void setLanguage(GpuLanguage lang);
1155        //!cpp:function::
1156        GpuLanguage getLanguage() const;
1157        
1158        //!cpp:function::
1159        void setFunctionName(const char * name);
1160        //!cpp:function::
1161        const char * getFunctionName() const;
1162        
1163        //!cpp:function::
1164        void setLut3DEdgeLen(int len);
1165        //!cpp:function::
1166        int getLut3DEdgeLen() const;
1167        
1168        //!cpp:function:: 
1169        const char * getCacheID() const;
1170        
1171    private:
1172        
1173        GpuShaderDesc(const GpuShaderDesc &);
1174        GpuShaderDesc& operator= (const GpuShaderDesc &);
1175        
1176        class Impl;
1177        friend class Impl;
1178        Impl * m_impl;
1179        Impl * getImpl() { return m_impl; }
1180        const Impl * getImpl() const { return m_impl; }
1181    };
1182    
1183    
1184    ///////////////////////////////////////////////////////////////////////////
1185    //!rst::
1186    // Context
1187    // *******
1188    
1189    //!cpp:class::
1190    class OCIOEXPORT Context
1191    {
1192    public:
1193        //!cpp:function::
1194        static ContextRcPtr Create();
1195        
1196        //!cpp:function::
1197        ContextRcPtr createEditableCopy() const;
1198        
1199        //!cpp:function:: 
1200        const char * getCacheID() const;
1201        
1202        //!cpp:function::
1203        void setSearchPath(const char * path);
1204        //!cpp:function::
1205        const char * getSearchPath() const;
1206        
1207        //!cpp:function::
1208        void setWorkingDir(const char * dirname);
1209        //!cpp:function::
1210        const char * getWorkingDir() const;
1211        
1212        //!cpp:function::
1213        void setStringVar(const char * name, const char * value);
1214        //!cpp:function::
1215        const char * getStringVar(const char * name) const;
1216        
1217        //!cpp:function::
1218        int getNumStringVars() const;
1219        //!cpp:function::
1220        const char * getStringVarNameByIndex(int index) const;
1221        
1222        //!cpp:function::
1223        void clearStringVars();
1224        
1225        //!cpp:function::
1226        void setEnvironmentMode(EnvironmentMode mode);
1227        
1228        //!cpp:function::
1229        EnvironmentMode getEnvironmentMode() const;
1230        
1231        //!cpp:function:: Seed all string vars with the current environment.
1232        void loadEnvironment();
1233        
1234        //! Do a string lookup.
1235        //!cpp:function:: Do a file lookup.
1236        // 
1237        // Evaluate the specified variable (as needed). Will not throw exceptions.
1238        const char * resolveStringVar(const char * val) const;
1239        
1240        //! Do a file lookup.
1241        //!cpp:function:: Do a file lookup.
1242        // 
1243        // Evaluate all variables (as needed).
1244        // Also, walk the full search path until the file is found.
1245        // If the filename cannot be found, an exception will be thrown.
1246        const char * resolveFileLocation(const char * filename) const;
1247    
1248    private:
1249        Context();
1250        ~Context();
1251        
1252        Context(const Context &);
1253        Context& operator= (const Context &);
1254        
1255        static void deleter(Context* c);
1256        
1257        class Impl;
1258        friend class Impl;
1259        Impl * m_impl;
1260        Impl * getImpl() { return m_impl; }
1261        const Impl * getImpl() const { return m_impl; }
1262    };
1263    
1264    extern OCIOEXPORT std::ostream& operator<< (std::ostream&, const Context&);
1265}
1266OCIO_NAMESPACE_EXIT
1267
1268#endif // INCLUDED_OCIO_OPENCOLORIO_H