doc/mainpage.txt

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