doc/mainpage.txt

   1 /*!
   2
   3 @mainpage libdcp
   4
   5 libdcp is a small library to create and read Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
   6
   7 Most of the hard work is done by a (slightly patched) version of asdcplib (http://www.cinecert.com/asdcplib/)
   8 which is included in the source distribution for libdcp.
   9
  10 libdcp is distributed under the GNU GPL.
  11
  12 Creating DCPs
  13 --
  14
  15 An example of DCP creation is given in examples/make_dcp.cc.
  16
  17 Reading existing DCPs
  18 --
  19
  20 Alternatively libdcp can be used to read existing DCPs and examine their content.  You might do
  21
  22 @code
  23 #include <libdcp/dcp.h>
  24 using namespace std;
  25
  26 libdcp::DCP dcp ("some-DCP-directory");
  27 @endcode
  28
  29 libdcp will look at the XML files that make up the DCP and find its assets.  You can then
  30 do things like
  31
  32 @code
  33 boost::shared_ptr<Reel> reel = dcp.reels.front ();
  34 boost::shared_ptr<libdcp::PictureAsset> p = reel->main_picture ();
  35 boost::shared_ptr<libdcp::MonoPictureAsset> mp = boost::dynamic_pointer_cast<libdcp::MonoPictureAsset> (p);
  36 boost::shared_ptr<libdcp::ARGBFrame> f = mp->get_frame(42)->argb_frame ();
  37 uint8_t* data = f->data ();
  38 int size = f->size ();
  39 @endcode
  40
  41 This will extract the image of frame 42 from the first reel of the DCP and make its ARGB data available
  42 for examination.  We have to do a <code>dynamic_pointer_cast</code> from <code>libdcp::PictureAsset</code>
  43 to <code>libdcp::MonoPictureAsset</code>, as the picture asset may be either 2D (monoscopic) or 3D (stereoscopic).
  44
  45 Audio data is accessed in chunks equal in length to the duration of a video frame.  To
  46 get the audio that accompanies frame 66, you can do
  47
  48 @code
  49 boost::shared_ptr<libdcp::SoundAsset> s = reel->main_sound ();
  50 cout << "Sound has " << s->channels() << " channels at " << s->sampling_rate() << "Hz\n";
  51 boost::shared_ptr<libdcp::SoundFrame> f = s->get_frame(66);
  52 uint8_t* data = f->data ();
  53 int size = f->size ();
  54 @endcode
  55
  56 The returned data are interleaved 24-bit samples, so that
  57
  58 @code
  59 int left = data[0] | (data[1] << 8) | (data[2] << 16);
  60 data += 3;
  61 int right = data[0] | (data[1] << 8) | (data[2] << 16);
  62 data += 3;
  63 int centre = data[0] | (data[1] << 8) | (data[2] << 16);
  64 data += 3;
  65 int lfe = data[0] | (data[1] << 8) | (data[2] << 16);
  66 data += 3;
  67 int ls = data[0] | (data[1] << 8) | (data[2] << 16);
  68 data += 3;
  69 int rs = data[0] | (data[1] << 8) | (data[2] << 16);
  70 data += 3;
  71 @endcode
  72
  73 would obtain the first sample from each of the 6 channels for that frame.
  74
  75 Subtitles can be read using code like
  76
  77 @code
  78 boost::shared_ptr<SubtitleAsset> s = dcp.subtitle_asset ();
  79 list<boost::shared_ptr<libdcp::Text> > texts = s->subtitles_at (libdcp::Time (0, 3, 2, 5));
  80 @endcode
  81
  82 This returns the subtitles that should be shown at 3 minutes, 2
  83 seconds, 5 ticks (where 1 tick is 4ms) into the DCP.
  84
  85 */
  86
  87