src/types.h

   1 /*
   2     Copyright (C) 2012-2021 Carl Hetherington <cth@carlh.net>
   3
   4     This file is part of libdcp.
   5
   6     libdcp is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 2 of the License, or
   9     (at your option) any later version.
  10
  11     libdcp is distributed in the hope that it will be useful,
  12     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14     GNU General Public License for more details.
  15
  16     You should have received a copy of the GNU General Public License
  17     along with libdcp.  If not, see <http://www.gnu.org/licenses/>.
  18
  19     In addition, as a special exception, the copyright holders give
  20     permission to link the code of portions of this program with the
  21     OpenSSL library under certain conditions as described in each
  22     individual source file, and distribute linked combinations
  23     including the two.
  24
  25     You must obey the GNU General Public License in all respects
  26     for all of the code used other than OpenSSL.  If you modify
  27     file(s) with this exception, you may extend this exception to your
  28     version of the file(s), but you are not obligated to do so.  If you
  29     do not wish to do so, delete this exception statement from your
  30     version.  If you delete this exception statement from all source
  31     files in the program, then also delete it here.
  32 */
  33
  34
  35 /** @file  src/types.h
  36  *  @brief Miscellaneous types
  37  */
  38
  39
  40 #ifndef LIBDCP_TYPES_H
  41 #define LIBDCP_TYPES_H
  42
  43
  44 #include "warnings.h"
  45 #include <libcxml/cxml.h>
  46 LIBDCP_DISABLE_WARNINGS
  47 #include <asdcp/KLV.h>
  48 LIBDCP_ENABLE_WARNINGS
  49 #include <memory>
  50 #include <boost/function.hpp>
  51 #include <string>
  52
  53
  54 /* MinGW seems to define this, but we want to use it */
  55 #undef ERROR
  56
  57
  58 namespace xmlpp {
  59         class Element;
  60 }
  61
  62
  63 namespace dcp
  64 {
  65
  66
  67 /** @struct Size
  68  *  @brief The integer, two-dimensional size of something.
  69  */
  70 struct Size
  71 {
  72         Size ()
  73                 : width (0)
  74                 , height (0)
  75         {}
  76
  77         Size (int w, int h)
  78                 : width (w)
  79                 , height (h)
  80         {}
  81
  82         float ratio () const {
  83                 return float (width) / height;
  84         }
  85
  86         int width;
  87         int height;
  88 };
  89
  90
  91 extern bool operator== (Size const & a, Size const & b);
  92 extern bool operator!= (Size const & a, Size const & b);
  93
  94
  95 /** Identifier for a sound channel */
  96 enum class Channel {
  97         LEFT = 0,      ///< left
  98         RIGHT = 1,     ///< right
  99         CENTRE = 2,    ///< centre
 100         LFE = 3,       ///< low-frequency effects (sub)
 101         LS = 4,        ///< left surround
 102         RS = 5,        ///< right surround
 103         HI = 6,
 104         VI = 7,
 105         /* 8 and 9 are not used */
 106         BSL = 10,
 107         BSR = 11,
 108         MOTION_DATA = 12,
 109         SYNC_SIGNAL = 13,
 110         SIGN_LANGUAGE = 14,
 111         /* 15 is not used */
 112         CHANNEL_COUNT = 16
 113 };
 114
 115
 116 std::vector<dcp::Channel> used_audio_channels ();
 117
 118
 119 enum class MCASoundField
 120 {
 121         STEREO,
 122         FIVE_POINT_ONE,
 123         SEVEN_POINT_ONE
 124 };
 125
 126
 127 extern std::string channel_to_mca_id (Channel c, MCASoundField field);
 128 extern Channel mca_id_to_channel (std::string);
 129 extern std::string channel_to_mca_name (Channel c, MCASoundField field);
 130 extern ASDCP::UL channel_to_mca_universal_label (Channel c, MCASoundField field, ASDCP::Dictionary const* dict);
 131
 132
 133 enum class Effect
 134 {
 135         NONE,
 136         BORDER,
 137         SHADOW
 138 };
 139
 140
 141 extern std::string effect_to_string (Effect e);
 142 extern Effect string_to_effect (std::string s);
 143
 144
 145 enum class HAlign
 146 {
 147         LEFT,   ///< horizontal position is distance from left of screen to left of subtitle
 148         CENTER, ///< horizontal position is distance from centre of screen to centre of subtitle
 149         RIGHT,  ///< horizontal position is distance from right of screen to right of subtitle
 150 };
 151
 152
 153 extern std::string halign_to_string (HAlign a);
 154 extern HAlign string_to_halign (std::string s);
 155
 156
 157 enum class VAlign
 158 {
 159         /** vertical position is distance:
 160          *    from top of screen to top of subtitle (for SMPTE) or
 161          *    from top of screen to subtitle baseline (for Interop)
 162          */
 163         TOP,
 164         /** vertical position is distance:
 165          *    from centre of screen to centre of subtitle (for SMPTE) or
 166          *    from centre of screen to subtitle baseline (for Interop)
 167          */
 168         CENTER,
 169         /** vertical position is distance:
 170          *    from bottom of screen to bottom of subtitle (for SMPTE) or
 171          *    from bottom of screen to subtitle baseline (for Interop)
 172          */
 173         BOTTOM
 174 };
 175
 176
 177 extern std::string valign_to_string (VAlign a);
 178 extern VAlign string_to_valign (std::string s);
 179
 180
 181 /** Direction for subtitle test */
 182 enum class Direction
 183 {
 184         LTR, ///< left-to-right
 185         RTL, ///< right-to-left
 186         TTB, ///< top-to-bottom
 187         BTT  ///< bottom-to-top
 188 };
 189
 190
 191 extern std::string direction_to_string (Direction a);
 192 extern Direction string_to_direction (std::string s);
 193
 194
 195 enum class Eye
 196 {
 197         LEFT,
 198         RIGHT
 199 };
 200
 201
 202 /** @class Fraction
 203  *  @brief A fraction (i.e. a thing with an integer numerator and an integer denominator).
 204  */
 205 class Fraction
 206 {
 207 public:
 208         /** Construct a fraction of 0/0 */
 209         Fraction () {}
 210         explicit Fraction (std::string s);
 211         /** Construct a fraction with a specified numerator and denominator.
 212          *  @param n Numerator.
 213          *  @param d Denominator.
 214          */
 215         Fraction (int n, int d) : numerator (n), denominator (d) {}
 216
 217         float as_float () const {
 218                 return float (numerator) / denominator;
 219         }
 220
 221         std::string as_string () const;
 222
 223         int numerator = 0;
 224         int denominator = 0;
 225 };
 226
 227
 228 extern bool operator== (Fraction const & a, Fraction const & b);
 229 extern bool operator!= (Fraction const & a, Fraction const & b);
 230
 231
 232 /** @struct EqualityOptions
 233  *  @brief  A class to describe what "equality" means for a particular test.
 234  *
 235  *  When comparing things, we want to be able to ignore some differences;
 236  *  this class expresses those differences.
 237  *
 238  *  It also contains some settings for how the comparison should be done.
 239  */
 240 struct EqualityOptions
 241 {
 242         /** Construct an EqualityOptions where nothing at all can differ */
 243         EqualityOptions () {}
 244
 245         /** The maximum allowable mean difference in pixel value between two images */
 246         double max_mean_pixel_error = 0;
 247         /** The maximum standard deviation of the differences in pixel value between two images */
 248         double max_std_dev_pixel_error = 0;
 249         /** The maximum difference in audio sample value between two soundtracks */
 250         int max_audio_sample_error = 0;
 251         /** true if the &lt;AnnotationText&gt; nodes of CPLs are allowed to differ */
 252         bool cpl_annotation_texts_can_differ = false;
 253         /** true if the &lt;AnnotationText&gt; nodes of Reels are allowed to differ */
 254         bool reel_annotation_texts_can_differ = false;
 255         /** true if <Hash>es in Reels can differ */
 256         bool reel_hashes_can_differ = false;
 257         /** true if IssueDate nodes can differ */
 258         bool issue_dates_can_differ = false;
 259         bool load_font_nodes_can_differ = false;
 260         bool keep_going = false;
 261         /** true to save the first pair of differeng image subtitles to the current working directory */
 262         bool export_differing_subtitles = false;
 263         /** The maximum allowable absolute difference between the vertical position of subtitles */
 264         float max_subtitle_vertical_position_error = 0;
 265 };
 266
 267
 268 enum class NoteType {
 269         PROGRESS,
 270         ERROR,
 271         NOTE
 272 };
 273
 274
 275 enum class Standard {
 276         INTEROP,
 277         SMPTE
 278 };
 279
 280
 281 enum class Formulation {
 282         MODIFIED_TRANSITIONAL_1,
 283         MULTIPLE_MODIFIED_TRANSITIONAL_1,
 284         DCI_ANY,
 285         DCI_SPECIFIC,
 286 };
 287
 288
 289 std::string formulation_to_string (dcp::Formulation formulation);
 290 dcp::Formulation string_to_formulation (std::string forumulation);
 291
 292
 293 /** @class Colour
 294  *  @brief An RGB colour
 295  */
 296 class Colour
 297 {
 298 public:
 299         /** Construct a Colour, initialising it to black */
 300         Colour ();
 301
 302         /** Construct a Colour from R, G and B.  The values run between
 303          *  0 and 255.
 304          */
 305         Colour (int r_, int g_, int b_);
 306
 307         /** Construct a Colour from an ARGB hex string; the alpha value is ignored.
 308          *  @param argb_hex A string of the form AARRGGBB, where e.g. RR is a two-character
 309          *  hex value.
 310          */
 311         explicit Colour (std::string argb_hex);
 312
 313         int r = 0; ///< red component, from 0 to 255
 314         int g = 0; ///< green component, from 0 to 255
 315         int b = 0; ///< blue component, from 0 to 255
 316
 317         /** @return An RGB string of the form RRGGBB, where e.g. RR is a two-character
 318          *  hex value.
 319          */
 320         std::string to_rgb_string () const;
 321
 322         /** @return An ARGB string of the form AARRGGBB, where e.g. RR is a two-character
 323          *  hex value.  The alpha value will always be FF (ie 255; maximum alpha).
 324          */
 325         std::string to_argb_string () const;
 326 };
 327
 328
 329 extern bool operator== (Colour const & a, Colour const & b);
 330 extern bool operator!= (Colour const & a, Colour const & b);
 331
 332
 333 typedef boost::function<void (NoteType, std::string)> NoteHandler;
 334
 335
 336 /** Maximum absolute difference between dcp::SubtitleString::aspect_adjust values that
 337  *  are considered equal
 338  */
 339 constexpr float ASPECT_ADJUST_EPSILON = 1e-3;
 340
 341
 342 /** Maximum absolute difference between dcp::SubtitleString alignment values that
 343  *  are considered equal.
 344  */
 345 constexpr float ALIGN_EPSILON = 1e-3;
 346
 347
 348 /** Maximum absolute difference between dcp::SubtitleString space_before values that
 349  *  are considered equal.
 350  */
 351 constexpr float SPACE_BEFORE_EPSILON = 1e-3;
 352
 353
 354 enum class Marker {
 355         FFOC, ///< first frame of composition
 356         LFOC, ///< last frame of composition
 357         FFTC, ///< first frame of title credits
 358         LFTC, ///< last frame of title credits
 359         FFOI, ///< first frame of intermission
 360         LFOI, ///< last frame of intermission
 361         FFEC, ///< first frame of end credits
 362         LFEC, ///< last frame of end credits
 363         FFMC, ///< first frame of moving credits
 364         LFMC  ///< last frame of moving credits
 365 };
 366
 367
 368 std::string marker_to_string (Marker);
 369 Marker marker_from_string (std::string);
 370
 371
 372 enum class Status
 373 {
 374         FINAL, ///< final version
 375         TEMP,  ///< temporary version (picture/sound unfinished)
 376         PRE    ///< pre-release (picture/sound finished)
 377 };
 378
 379
 380 extern std::string status_to_string (Status s);
 381 extern Status string_to_status (std::string s);
 382
 383
 384 class ContentVersion
 385 {
 386 public:
 387         ContentVersion ();
 388
 389         explicit ContentVersion (cxml::ConstNodePtr node);
 390
 391         explicit ContentVersion (std::string label_text_);
 392
 393         ContentVersion (std::string id_, std::string label_text_)
 394                 : id (id_)
 395                 , label_text (label_text_)
 396         {}
 397
 398         void as_xml (xmlpp::Element* parent) const;
 399
 400         std::string id;
 401         std::string label_text;
 402 };
 403
 404
 405 class Luminance
 406 {
 407 public:
 408         enum class Unit {
 409                 CANDELA_PER_SQUARE_METRE,
 410                 FOOT_LAMBERT
 411         };
 412
 413         Luminance (cxml::ConstNodePtr node);
 414
 415         Luminance (float value, Unit unit);
 416
 417         void set_value (float v);
 418         void set_unit (Unit u) {
 419                 _unit = u;
 420         }
 421
 422         float value () const {
 423                 return _value;
 424         }
 425
 426         Unit unit () const {
 427                 return _unit;
 428         }
 429
 430         float value_in_foot_lamberts () const;
 431
 432         void as_xml (xmlpp::Element* parent, std::string ns) const;
 433
 434         static std::string unit_to_string (Unit u);
 435         static Unit string_to_unit (std::string u);
 436
 437 private:
 438         float _value;
 439         Unit _unit;
 440 };
 441
 442
 443 bool operator== (Luminance const& a, Luminance const& b);
 444
 445
 446 class MainSoundConfiguration
 447 {
 448 public:
 449         MainSoundConfiguration (std::string);
 450         MainSoundConfiguration (MCASoundField field_, int channels);
 451
 452         MCASoundField field () const {
 453                 return _field;
 454         }
 455
 456         int channels () const {
 457                 return _channels.size();
 458         }
 459
 460         boost::optional<Channel> mapping (int index) const;
 461         void set_mapping (int index, Channel channel);
 462
 463         std::string to_string () const;
 464
 465 private:
 466         MCASoundField _field;
 467         std::vector<boost::optional<Channel>> _channels;
 468 };
 469
 470
 471 }
 472
 473
 474 #endif