1 /////////////////////////////////////////////////////////////////////////// 2 // 3 // Copyright (c) 2004, Industrial Light & Magic, a division of Lucas 4 // Digital Ltd. LLC 5 // 6 // All rights reserved. 7 // 8 // Redistribution and use in source and binary forms, with or without 9 // modification, are permitted provided that the following conditions are 10 // met: 11 // * Redistributions of source code must retain the above copyright 12 // notice, this list of conditions and the following disclaimer. 13 // * Redistributions in binary form must reproduce the above 14 // copyright notice, this list of conditions and the following disclaimer 15 // in the documentation and/or other materials provided with the 16 // distribution. 17 // * Neither the name of Industrial Light & Magic nor the names of 18 // its contributors may be used to endorse or promote products derived 19 // from this software without specific prior written permission. 20 // 21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 // 33 /////////////////////////////////////////////////////////////////////////// 34 35 36 37 #ifndef INCLUDED_IMF_RGBA_FILE_H 38 #define INCLUDED_IMF_RGBA_FILE_H 39 40 41 //----------------------------------------------------------------------------- 42 // 43 // Simplified RGBA image I/O 44 // 45 // class RgbaOutputFile 46 // class RgbaInputFile 47 // 48 //----------------------------------------------------------------------------- 49 50 #include <ImfHeader.h> 51 #include <ImfFrameBuffer.h> 52 #include <ImfRgba.h> 53 #include "ImathVec.h" 54 #include "ImathBox.h" 55 #include "half.h" 56 #include <ImfThreading.h> 57 #include <string> 58 59 namespace Imf { 60 61 62 class OutputFile; 63 class InputFile; 64 struct PreviewRgba; 65 66 // 67 // RGBA output file. 68 // 69 70 class RgbaOutputFile 71 { 72 public: 73 74 //--------------------------------------------------- 75 // Constructor -- header is constructed by the caller 76 //--------------------------------------------------- 77 78 RgbaOutputFile (const char name[], 79 const Header &header, 80 RgbaChannels rgbaChannels = WRITE_RGBA, 81 int numThreads = globalThreadCount()); 82 83 84 //---------------------------------------------------- 85 // Constructor -- header is constructed by the caller, 86 // file is opened by the caller, destructor will not 87 // automatically close the file. 88 //---------------------------------------------------- 89 90 RgbaOutputFile (OStream &os, 91 const Header &header, 92 RgbaChannels rgbaChannels = WRITE_RGBA, 93 int numThreads = globalThreadCount()); 94 95 96 //---------------------------------------------------------------- 97 // Constructor -- header data are explicitly specified as function 98 // call arguments (empty dataWindow means "same as displayWindow") 99 //---------------------------------------------------------------- 100 101 RgbaOutputFile (const char name[], 102 const Imath::Box2i &displayWindow, 103 const Imath::Box2i &dataWindow = Imath::Box2i(), 104 RgbaChannels rgbaChannels = WRITE_RGBA, 105 float pixelAspectRatio = 1, 106 const Imath::V2f screenWindowCenter = Imath::V2f (0, 0), 107 float screenWindowWidth = 1, 108 LineOrder lineOrder = INCREASING_Y, 109 Compression compression = PIZ_COMPRESSION, 110 int numThreads = globalThreadCount()); 111 112 113 //----------------------------------------------- 114 // Constructor -- like the previous one, but both 115 // the display window and the data window are 116 // Box2i (V2i (0, 0), V2i (width - 1, height -1)) 117 //----------------------------------------------- 118 119 RgbaOutputFile (const char name[], 120 int width, 121 int height, 122 RgbaChannels rgbaChannels = WRITE_RGBA, 123 float pixelAspectRatio = 1, 124 const Imath::V2f screenWindowCenter = Imath::V2f (0, 0), 125 float screenWindowWidth = 1, 126 LineOrder lineOrder = INCREASING_Y, 127 Compression compression = PIZ_COMPRESSION, 128 int numThreads = globalThreadCount()); 129 130 131 //----------- 132 // Destructor 133 //----------- 134 135 virtual ~RgbaOutputFile (); 136 137 138 //------------------------------------------------ 139 // Define a frame buffer as the pixel data source: 140 // Pixel (x, y) is at address 141 // 142 // base + x * xStride + y * yStride 143 // 144 //------------------------------------------------ 145 146 void setFrameBuffer (const Rgba *base, 147 size_t xStride, 148 size_t yStride); 149 150 151 //--------------------------------------------- 152 // Write pixel data (see class Imf::OutputFile) 153 //--------------------------------------------- 154 155 void writePixels (int numScanLines = 1); 156 int currentScanLine () const; 157 158 159 //-------------------------- 160 // Access to the file header 161 //-------------------------- 162 163 const Header & header () const; 164 const FrameBuffer & frameBuffer () const; 165 const Imath::Box2i & displayWindow () const; 166 const Imath::Box2i & dataWindow () const; 167 float pixelAspectRatio () const; 168 const Imath::V2f screenWindowCenter () const; 169 float screenWindowWidth () const; 170 LineOrder lineOrder () const; 171 Compression compression () const; 172 RgbaChannels channels () const; 173 174 175 // -------------------------------------------------------------------- 176 // Update the preview image (see Imf::OutputFile::updatePreviewImage()) 177 // -------------------------------------------------------------------- 178 179 void updatePreviewImage (const PreviewRgba[]); 180 181 182 //----------------------------------------------------------------------- 183 // Rounding control for luminance/chroma images: 184 // 185 // If the output file contains luminance and chroma channels (WRITE_YC 186 // or WRITE_YCA), then the the significands of the luminance and 187 // chroma values are rounded to roundY and roundC bits respectively (see 188 // function half::round()). Rounding improves compression with minimal 189 // image degradation, usually much less than the degradation caused by 190 // chroma subsampling. By default, roundY is 7, and roundC is 5. 191 // 192 // If the output file contains RGB channels or a luminance channel, 193 // without chroma, then no rounding is performed. 194 //----------------------------------------------------------------------- 195 196 void setYCRounding (unsigned int roundY, 197 unsigned int roundC); 198 199 200 //---------------------------------------------------- 201 // Break a scan line -- for testing and debugging only 202 // (see Imf::OutputFile::updatePreviewImage() 203 // 204 // Warning: Calling this function usually results in a 205 // broken image file. The file or parts of it may not 206 // be readable, or the file may contain bad data. 207 // 208 //---------------------------------------------------- 209 210 void breakScanLine (int y, 211 int offset, 212 int length, 213 char c); 214 private: 215 216 RgbaOutputFile (const RgbaOutputFile &); // not implemented 217 RgbaOutputFile & operator = (const RgbaOutputFile &); // not implemented 218 219 class ToYca; 220 221 OutputFile * _outputFile; 222 ToYca * _toYca; 223 }; 224 225 226 // 227 // RGBA input file 228 // 229 230 class RgbaInputFile 231 { 232 public: 233 234 //------------------------------------------------------- 235 // Constructor -- opens the file with the specified name, 236 // destructor will automatically close the file. 237 //------------------------------------------------------- 238 239 RgbaInputFile (const char name[], int numThreads = globalThreadCount()); 240 241 242 //----------------------------------------------------------- 243 // Constructor -- attaches the new RgbaInputFile object to a 244 // file that has already been opened by the caller. 245 // Destroying the RgbaInputFile object will not automatically 246 // close the file. 247 //----------------------------------------------------------- 248 249 RgbaInputFile (IStream &is, int numThreads = globalThreadCount()); 250 251 252 //-------------------------------------------------------------- 253 // Constructors -- the same as the previous two, but the names 254 // of the red, green, blue, alpha, luminance and chroma channels 255 // are expected to be layerName.R, layerName.G, etc. 256 //-------------------------------------------------------------- 257 258 RgbaInputFile (const char name[], 259 const std::string &layerName, 260 int numThreads = globalThreadCount()); 261 262 RgbaInputFile (IStream &is, 263 const std::string &layerName, 264 int numThreads = globalThreadCount()); 265 266 267 //----------- 268 // Destructor 269 //----------- 270 271 virtual ~RgbaInputFile (); 272 273 274 //----------------------------------------------------- 275 // Define a frame buffer as the pixel data destination: 276 // Pixel (x, y) is at address 277 // 278 // base + x * xStride + y * yStride 279 // 280 //----------------------------------------------------- 281 282 void setFrameBuffer (Rgba *base, 283 size_t xStride, 284 size_t yStride); 285 286 287 //---------------------------------------------------------------- 288 // Switch to a different layer -- subsequent calls to readPixels() 289 // will read channels layerName.R, layerName.G, etc. 290 // After each call to setLayerName(), setFrameBuffer() must be 291 // called at least once before the next call to readPixels(). 292 //---------------------------------------------------------------- 293 294 void setLayerName (const std::string &layerName); 295 296 297 //------------------------------------------- 298 // Read pixel data (see class Imf::InputFile) 299 //------------------------------------------- 300 301 void readPixels (int scanLine1, int scanLine2); 302 void readPixels (int scanLine); 303 304 305 //-------------------------- 306 // Access to the file header 307 //-------------------------- 308 309 const Header & header () const; 310 const FrameBuffer & frameBuffer () const; 311 const Imath::Box2i & displayWindow () const; 312 const Imath::Box2i & dataWindow () const; 313 float pixelAspectRatio () const; 314 const Imath::V2f screenWindowCenter () const; 315 float screenWindowWidth () const; 316 LineOrder lineOrder () const; 317 Compression compression () const; 318 RgbaChannels channels () const; 319 const char * fileName () const; 320 bool isComplete () const; 321 322 323 //---------------------------------- 324 // Access to the file format version 325 //---------------------------------- 326 327 int version () const; 328 329 private: 330 331 RgbaInputFile (const RgbaInputFile &); // not implemented 332 RgbaInputFile & operator = (const RgbaInputFile &); // not implemented 333 334 class FromYca; 335 336 InputFile * _inputFile; 337 FromYca * _fromYca; 338 std::string _channelNamePrefix; 339 }; 340 341 342 } // namespace Imf 343 344 #endif 345