Some comments.

5 files changed, 132 insertions, 9 deletions

diff --git a/doc/mainpage.txt b/doc/mainpage.txt
index 9d7139fa..f4394926 100644
--- a/doc/mainpage.txt
+++ b/doc/mainpage.txt
@@ -2,14 +2,17 @@
 
 @mainpage libdcp
 
-libdcp is a small library to create Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
+libdcp is a small library to create and read Digital Cinema Packages (DCPs) from JPEG2000 and WAV files.
 
 Most of the hard work is done by a (slightly patched) version of asdcplib (http://www.cinecert.com/asdcplib/)
 which is included in the source distribution for libdcp.
 
 libdcp is distributed under the GNU GPL.
 
-Typical use might be:
+Creating DCPs
+--
+
+Typical use for creating DCPs might be:
 @code
 #include <libdcp/dcp.h>
 using namespace std;
@@ -45,7 +48,17 @@ MXF files inside the DCP directory) and then write the required XML files.
 If you want to report progress for long jobs (add_picture_asset() can
 take a long time, in particular, as it must do a lot of disk I/O for
 large DCPs), connect to the libdcp::DCP::Progress signal and report its parameter
-to the user (it will range between 0 for 0% and 1 for 100%).
+to the user (it will range between 0 for 0% and 1 for 100%) using something like
+
+@code
+void
+report (float p)
+{
+   cout << "We are " << int (p * 100) << "% done.\n";
+}
+
+dcp.Progress.connect (sigc::ptr_fun (&report));
+@endcode
 
 If you can generate content paths algorithmically, you may prefer to do something
 like this:
@@ -84,6 +97,72 @@ dcp.add_sound_asset (sigc::ptr_fun (&wav_path), 2);
 
 @endcode
 
+Reading existing DCPs
+--
+
+Alternatively libdcp can be used to read existing DCPs and examine their content.  You
+might do
+
+@code
+#include <libdcp/dcp.h>
+using namespace std;
+
+libdcp::DCP dcp ("some-DCP-directory");
+@endcode
+
+libdcp will look at the XML files that make up the DCP and find its assets.  You can then
+do things like
+
+@code
+boost::shared_ptr<libdcp::PictureAsset> p = dcp.picture_asset ();
+boost::shared_ptr<libdcp::RGBAFrame> f = p->get_frame(42)->rgba_frame ();
+uint8_t* data = f->data ();
+int size = f->size ();
+@endcode
+
+This will extract the image of frame 42 from the DCP and make its RGBA data available
+for examination.
+
+Audio data is accessed in chunks equal in length to the duration of a video frame.  To
+get the audio that accompanies frame 66, you can do
+
+@code
+boost::shared_ptr<libdcp::SoundAsset> s = dcp.sound_asset ();
+cout << "Sound has " << s->channels() << " channels at " << s->sampling_rate() << "Hz\n";
+boost::shared_ptr<libdcp::SoundFrame> f = s->get_frame(66);
+uint8_t* data = f->data ();
+int size = f->size ();
+@endcode
+
+The returned data is interleaved 24-bit samples, so that
+
+@code
+int left = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int right = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int centre = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int lfe = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int ls = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+int rs = data[0] | (data[1] << 8) | (data[2] << 16);
+data += 3;
+@endcode
+
+would obtain the first sample from each of the 6 channels for that frame.
+
+Subtitles can be read using code like
+
+@code
+boost::shared_ptr<SubtitleAsset> s = dcp.subtitle_asset ();
+list<boost::shared_ptr<libdcp::Text> > texts = s->subtitles_at (libdcp::Time (0, 3, 2, 5));
+@endcode
+
+This returns the subtitles that should be shown at 3 minutes, 2
+seconds, 5 ticks (where 1 tick is 4ms) into the DCP.
+
 */
 
 
diff --git a/src/dcp.h b/src/dcp.h
index 60135c2e..fb3bd751 100644
--- a/src/dcp.h
+++ b/src/dcp.h
@@ -51,6 +51,9 @@ class DCP
 {
 public:
 	/** Construct a DCP.
+	 *
+	 *  This is for making a new DCP that you are going to add assets to.
+	 *
 	 *  @param directory Directory to write files to.
 	 *  @param name Name.
 	 *  @param content_kind Content kind.
@@ -59,6 +62,13 @@ public:
 	 */
 	DCP (std::string directory, std::string name, ContentKind content_kind, int fps, int length);
 
+	/** Construct a DCP object for an existing DCP.
+	 *
+	 *  The DCP's XML metadata will be examined, and you can then look at the contents
+	 *  of the DCP.
+	 *
+	 *  @param directory Existing DCP's directory.
+	 */
 	DCP (std::string directory);
 
 	/** Add a sound asset.
@@ -93,26 +103,43 @@ public:
 	 */
 	void write_xml () const;
 
+	/** @return the DCP's name, as will be presented on projector
+	 *  media servers and theatre management systems.
+	 */
 	std::string name () const {
 		return _name;
 	}
 
+	/** @return the type of the content, used by media servers
+	 *  to categorise things (e.g. feature, trailer, etc.)
+	 */
 	ContentKind content_kind () const {
 		return _content_kind;
 	}
 
+	/** @return the number of frames per second */
 	int frames_per_second () const {
 		return _fps;
 	}
 
+	/** @return the length in frames */
 	int length () const {
 		return _length;
 	}
 
+	/** @return the main picture asset, if one exists, otherwise 0 */
 	boost::shared_ptr<const PictureAsset> picture_asset () const;
+	/** @return the main sound asset, if one exists, otherwise 0 */
 	boost::shared_ptr<const SoundAsset> sound_asset () const;
+	/** @return the main subtitle asset, if one exists, otherwise 0 */
 	boost::shared_ptr<const SubtitleAsset> subtitle_asset () const;
 
+	/** Compare this DCP with another, according to various options.
+	 *  @param other DCP to compare this one to.
+	 *  @param options Options to define just what "equality" means.
+	 *  @return An empty list if the DCPs are equal; otherwise a list of messages
+	 *  which explain the ways in which they differ.
+	 */
 	std::list<std::string> equals (DCP const & other, EqualityOptions options) const;
 
 	/** Emitted with a parameter between 0 and 1 to indicate progress
diff --git a/src/dcp_time.cc b/src/dcp_time.cc
index f853143a..900d7c6e 100644
--- a/src/dcp_time.cc
+++ b/src/dcp_time.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/dcp_time.cc
+ *  @brief A representation of time within a DCP.
+ */
+
 #include <iostream>
 #include <cmath>
 #include "dcp_time.h"
diff --git a/src/dcp_time.h b/src/dcp_time.h
index a611cd89..626cdaca 100644
--- a/src/dcp_time.h
+++ b/src/dcp_time.h
@@ -17,16 +17,29 @@
 
 */
 
+/** @file  src/dcp_time.h
+ *  @brief A representation of time within a DCP.
+ */
+
 #ifndef LIBDCP_TIME_H
 #define LIBDCP_TIME_H
 
 namespace libdcp {
 
+/** @class Time
+ *  @brief A representation of time within a DCP.
+ */
+	
 class Time
 {
 public:
 	Time () : h (0), m (0), s (0), t (0) {}
+
+	/** Construct a Time from a frame index (starting from 0)
+	 *  and a frames per second count.
+	 */
 	Time (int frame, int frames_per_second);
+	
 	Time (int h_, int m_, int s_, int t_)
 		: h (h_)
 		, m (m_)
@@ -34,10 +47,10 @@ public:
 		, t (t_)
 	{}
 
-	int h;
-	int m;
-	int s;
-	int t;
+	int h; ///< hours
+	int m; ///< minutes
+	int s; ///< seconds
+	int t; ///< `ticks', where 1 tick is 4 milliseconds
 };
 
 extern bool operator== (Time const & a, Time const & b);
diff --git a/src/mxf_asset.h b/src/mxf_asset.h
index 35509311..d01d091d 100644
--- a/src/mxf_asset.h
+++ b/src/mxf_asset.h
@@ -30,12 +30,12 @@ class MXFAsset : public Asset
 public:
 	/** Construct an MXFAsset.
 	 *  @param directory Directory where MXF file is.
-	 *  @param mxf_name Name of MXF file.
+	 *  @param file_name Name of MXF file.
 	 *  @param progress Signal to inform of progress.
 	 *  @param fps Frames per second.
 	 *  @param length Length in frames.
 	 */
-	MXFAsset (std::string directory, std::string mxf_path, sigc::signal1<void, float>* progress, int fps, int length);
+	MXFAsset (std::string directory, std::string file_name, sigc::signal1<void, float>* progress, int fps, int length);
 
 	virtual std::list<std::string> equals (boost::shared_ptr<const Asset> other, EqualityOptions opt) const;