doc/mainpage.txt

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