/export/OpenColorIO/OpenColorIO.h
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