src/AS_02_PHDR.h

   1 /*
   2 Copyright (c) 2011-2018, John Hurst
   3
   4 All rights reserved.
   5
   6 Redistribution and use in source and binary forms, with or without
   7 modification, are permitted provided that the following conditions
   8 are met:
   9 1. Redistributions of source code must retain the above copyright
  10    notice, this list of conditions and the following disclaimer.
  11 2. Redistributions in binary form must reproduce the above copyright
  12    notice, this list of conditions and the following disclaimer in the
  13    documentation and/or other materials provided with the distribution.
  14 3. The name of the author may not be used to endorse or promote products
  15    derived from this software without specific prior written permission.
  16
  17 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 */
  28
  29 /*! \file    AS_02_PHDR.h
  30   \version $Id$
  31   \brief   AS-02 library, JPEG 2000 P-HDR essence reader and writer implementation
  32 */
  33
  34
  35 #ifndef _AS_02_PHDR_H_
  36 #define _AS_02_PHDR_H_
  37
  38 #include "AS_02.h"
  39
  40 namespace AS_02
  41 {
  42
  43   namespace PHDR
  44   {
  45     //
  46     class FrameBuffer : public ASDCP::JP2K::FrameBuffer
  47       {
  48       public:
  49         std::string OpaqueMetadata;
  50
  51         FrameBuffer() {}
  52         FrameBuffer(ui32_t size) { Capacity(size); }
  53         virtual ~FrameBuffer() {}
  54
  55         // Print debugging information to stream (stderr default)
  56         void Dump(FILE* = 0, ui32_t dump_bytes = 0) const;
  57       };
  58
  59     // An object which reads a sequence of files containing
  60     // JPEG 2000 P-HDR pictures and metadata.
  61     class SequenceParser
  62     {
  63       class h__SequenceParser;
  64       Kumu::mem_ptr<h__SequenceParser> m_Parser;
  65       ASDCP_NO_COPY_CONSTRUCT(SequenceParser);
  66
  67     public:
  68       SequenceParser();
  69       virtual ~SequenceParser();
  70
  71       // Opens a directory for reading.  The directory is expected to contain one or
  72       // more pairs of files, each containing the codestream for exactly one picture (.j2c)
  73       // and the corresponding P-HDR metadata (.xml). The files must be named such that the
  74       // frames are in temporal order when sorted alphabetically by filename. The parser
  75       // will automatically parse enough data from the first file to provide a complete set
  76       // of stream metadata for the MXFWriter below. The contents of the metadata files will
  77       // not be analyzed (i.e., the raw bytes will be passed in without scrutiny.) If the
  78       // "pedantic" parameter is given and is true, the J2C parser will check the JPEG 2000
  79       // metadata for each codestream and fail if a mismatch is detected.
  80       Result_t OpenRead(const std::string& filename, bool pedantic = false) const;
  81
  82       // Opens a file sequence for reading.  The sequence is expected to contain one or
  83       // more pairs of filenames, each naming a file containing the codestream (.j2c) and the
  84       // corresponding P-HDR metadata (.xml) for exactly one picture. The parser will
  85       // automatically parse enough data from the first file to provide a complete set of
  86       // stream metadata for the MXFWriter below.  If the "pedantic" parameter is given and
  87       // is true, the parser will check the metadata for each codestream and fail if a
  88       // mismatch is detected.
  89       Result_t OpenRead(const std::list<std::string>& file_list, bool pedantic = false) const;
  90
  91       // Fill a PictureDescriptor struct with the values from the first file's codestream.
  92       // Returns RESULT_INIT if the directory is not open.
  93       Result_t FillPictureDescriptor(ASDCP::JP2K::PictureDescriptor&) const;
  94
  95       // Rewind the directory to the beginning.
  96       Result_t Reset() const;
  97
  98       // Reads the next sequential frame in the directory and places it in the frame buffer.
  99       // Fails if the buffer is too small or the direcdtory contains no more files. The frame
 100       // buffer's PlaintextOffset parameter will be set to the first byte of the data segment.
 101       // Set this value to zero if you want encrypted headers.
 102       Result_t ReadFrame(AS_02::PHDR::FrameBuffer&) const;
 103     };
 104
 105     //
 106     class MXFWriter
 107     {
 108       class h__Writer;
 109       ASDCP::mem_ptr<h__Writer> m_Writer;
 110       ASDCP_NO_COPY_CONSTRUCT(MXFWriter);
 111
 112     public:
 113       MXFWriter();
 114       virtual ~MXFWriter();
 115
 116       // Warning: direct manipulation of MXF structures can interfere
 117       // with the normal operation of the wrapper.  Caveat emptor!
 118       virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
 119       virtual ASDCP::MXF::RIP& RIP();
 120
 121       // Open the file for writing. The file must not exist. Returns error if
 122       // the operation cannot be completed or if nonsensical data is discovered
 123       // in the essence descriptor.
 124       Result_t OpenWrite(const std::string& filename, const ASDCP::WriterInfo&,
 125                          ASDCP::MXF::FileDescriptor* essence_descriptor,
 126                          ASDCP::MXF::InterchangeObject_list_t& essence_sub_descriptor_list,
 127                          const ASDCP::Rational& edit_rate, const ui32_t& header_size = 16384,
 128                          const IndexStrategy_t& strategy = IS_FOLLOW, const ui32_t& partition_space = 10);
 129
 130       // Writes a frame of essence to the MXF file. If the optional AESEncContext
 131       // argument is present, the essence is encrypted prior to writing.
 132       // Fails if the file is not open, is finalized, or an operating system
 133       // error occurs.
 134       Result_t WriteFrame(const AS_02::PHDR::FrameBuffer&, ASDCP::AESEncContext* = 0, ASDCP::HMACContext* = 0);
 135
 136       // Closes the MXF file, writing the final index, the PHDR master metadata and the revised header.
 137       Result_t Finalize(const std::string& PHDR_master_metadata);
 138     };
 139
 140     //
 141     class MXFReader
 142     {
 143       class h__Reader;
 144       ASDCP::mem_ptr<h__Reader> m_Reader;
 145       ASDCP_NO_COPY_CONSTRUCT(MXFReader);
 146
 147     public:
 148       MXFReader();
 149       virtual ~MXFReader();
 150
 151       // Warning: direct manipulation of MXF structures can interfere
 152       // with the normal operation of the wrapper.  Caveat emptor!
 153       virtual ASDCP::MXF::OP1aHeader& OP1aHeader();
 154       virtual AS_02::MXF::AS02IndexReader& AS02IndexReader();
 155       virtual ASDCP::MXF::RIP& RIP();
 156
 157       // Open the file for reading. The file must exist. Returns error if the
 158       // operation cannot be completed. If master metadata is available it will
 159       // be placed into the string object passed as the second argument.
 160       Result_t OpenRead(const std::string& filename, std::string& PHDR_master_metadata) const;
 161
 162       // Returns RESULT_INIT if the file is not open.
 163       Result_t Close() const;
 164
 165       // Fill a WriterInfo struct with the values from the file's header.
 166       // Returns RESULT_INIT if the file is not open.
 167       Result_t FillWriterInfo(ASDCP::WriterInfo&) const;
 168
 169       // Reads a frame of essence from the MXF file. If the optional AESEncContext
 170       // argument is present, the essence is decrypted after reading. If the MXF
 171       // file is encrypted and the AESDecContext argument is NULL, the frame buffer
 172       // will contain the ciphertext frame data. If the HMACContext argument is
 173       // not NULL, the HMAC will be calculated (if the file supports it).
 174       // Returns RESULT_INIT if the file is not open, failure if the frame number is
 175       // out of range, or if optional decrypt or HAMC operations fail.
 176       Result_t ReadFrame(ui32_t frame_number, AS_02::PHDR::FrameBuffer&, ASDCP::AESDecContext* = 0, ASDCP::HMACContext* = 0) const;
 177
 178       // Print debugging information to stream
 179       void     DumpHeaderMetadata(FILE* = 0) const;
 180       void     DumpIndex(FILE* = 0) const;
 181     };
 182
 183   } // end namespace PHDR
 184
 185 } // end namespace AS_02
 186
 187 #endif // _AS_02_PHDR_H_
 188
 189 //
 190 // end AS_02_PHDR.h
 191 //