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         FIVE_POINT_ONE,
 122         SEVEN_POINT_ONE,
 123         OTHER
 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 428-7:{2007,2010} or
 161          *    from top of screen to subtitle baseline (for Interop or SMPTE 428-7:2014)
 162          */
 163         TOP,
 164         /** vertical position is distance:
 165          *    from centre of screen to centre of subtitle (for SMPTE 428-7:{2007,2010}) or
 166          *    from centre of screen to subtitle baseline (for Interop or SMPTE 428-7:2014)
 167          */
 168         CENTER,
 169         /** vertical position is distance:
 170          *    from bottom of screen to bottom of subtitle (for SMPTE 428-7:{2007,2010}) or
 171          *    from bottom of screen to subtitle baseline (for Interop or SMPTE 428-7:2014)
 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 /** @class 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 class EqualityOptions
 241 {
 242 public:
 243         /** Construct an EqualityOptions where nothing at all can differ */
 244         EqualityOptions() = default;
 245
 246         /** The maximum allowable mean difference in pixel value between two images */
 247         double max_mean_pixel_error = 0;
 248         /** The maximum standard deviation of the differences in pixel value between two images */
 249         double max_std_dev_pixel_error = 0;
 250         /** The maximum difference in audio sample value between two soundtracks */
 251         int max_audio_sample_error = 0;
 252         /** true if the &lt;AnnotationText&gt; nodes of CPLs are allowed to differ */
 253         bool cpl_annotation_texts_can_differ = false;
 254         /** true if the &lt;AnnotationText&gt; nodes of Reels are allowed to differ */
 255         bool reel_annotation_texts_can_differ = false;
 256         /** true if <Hash>es in Reels can differ */
 257         bool reel_hashes_can_differ = false;
 258         /** true if asset hashes can differ */
 259         bool asset_hashes_can_differ = false;
 260         /** true if IssueDate nodes can differ */
 261         bool issue_dates_can_differ = false;
 262         bool load_font_nodes_can_differ = false;
 263         bool keep_going = false;
 264         /** true to save the last pair of different image subtitles to the current working directory */
 265         bool export_differing_subtitles = false;
 266         /** The maximum allowable absolute difference between the vertical position of subtitles */
 267         float max_subtitle_vertical_position_error = 0;
 268 };
 269
 270
 271 enum class NoteType {
 272         PROGRESS,
 273         ERROR,
 274         NOTE
 275 };
 276
 277
 278 enum class Standard {
 279         INTEROP,
 280         SMPTE
 281 };
 282
 283
 284 enum class Formulation {
 285         MODIFIED_TRANSITIONAL_1,
 286         MULTIPLE_MODIFIED_TRANSITIONAL_1,
 287         DCI_ANY,
 288         DCI_SPECIFIC,
 289 };
 290
 291
 292 std::string formulation_to_string (dcp::Formulation formulation);
 293 dcp::Formulation string_to_formulation (std::string forumulation);
 294
 295
 296 /** @class Colour
 297  *  @brief An RGB colour
 298  */
 299 class Colour
 300 {
 301 public:
 302         /** Construct a Colour, initialising it to black */
 303         Colour ();
 304
 305         /** Construct a Colour from R, G and B.  The values run between
 306          *  0 and 255.
 307          */
 308         Colour (int r_, int g_, int b_);
 309
 310         /** Construct a Colour from an ARGB hex string; the alpha value is ignored.
 311          *  @param argb_hex A string of the form AARRGGBB, where e.g. RR is a two-character
 312          *  hex value.
 313          */
 314         explicit Colour (std::string argb_hex);
 315
 316         int r = 0; ///< red component, from 0 to 255
 317         int g = 0; ///< green component, from 0 to 255
 318         int b = 0; ///< blue component, from 0 to 255
 319
 320         /** @return An RGB string of the form RRGGBB, where e.g. RR is a two-character
 321          *  hex value.
 322          */
 323         std::string to_rgb_string () const;
 324
 325         /** @return An ARGB string of the form AARRGGBB, where e.g. RR is a two-character
 326          *  hex value.  The alpha value will always be FF (ie 255; maximum alpha).
 327          */
 328         std::string to_argb_string () const;
 329 };
 330
 331
 332 extern bool operator== (Colour const & a, Colour const & b);
 333 extern bool operator!= (Colour const & a, Colour const & b);
 334
 335
 336 typedef boost::function<void (NoteType, std::string)> NoteHandler;
 337
 338
 339 /** Maximum absolute difference between dcp::SubtitleString::aspect_adjust values that
 340  *  are considered equal
 341  */
 342 constexpr float ASPECT_ADJUST_EPSILON = 1e-3;
 343
 344
 345 /** Maximum absolute difference between dcp::SubtitleString alignment values that
 346  *  are considered equal.
 347  */
 348 constexpr float ALIGN_EPSILON = 1e-3;
 349
 350
 351 /** Maximum absolute difference between dcp::SubtitleString space_before values that
 352  *  are considered equal.
 353  */
 354 constexpr float SPACE_BEFORE_EPSILON = 1e-3;
 355
 356
 357 enum class Marker {
 358         FFOC, ///< first frame of composition
 359         LFOC, ///< last frame of composition
 360         FFTC, ///< first frame of title credits
 361         LFTC, ///< last frame of title credits
 362         FFOI, ///< first frame of intermission
 363         LFOI, ///< last frame of intermission
 364         FFEC, ///< first frame of end credits
 365         LFEC, ///< last frame of end credits
 366         FFMC, ///< first frame of moving credits
 367         LFMC  ///< last frame of moving credits
 368 };
 369
 370
 371 std::string marker_to_string (Marker);
 372 Marker marker_from_string (std::string);
 373
 374
 375 enum class Status
 376 {
 377         FINAL, ///< final version
 378         TEMP,  ///< temporary version (picture/sound unfinished)
 379         PRE    ///< pre-release (picture/sound finished)
 380 };
 381
 382
 383 extern std::string status_to_string (Status s);
 384 extern Status string_to_status (std::string s);
 385
 386
 387 class ContentVersion
 388 {
 389 public:
 390         ContentVersion ();
 391
 392         explicit ContentVersion (cxml::ConstNodePtr node);
 393
 394         explicit ContentVersion (std::string label_text_);
 395
 396         ContentVersion (std::string id_, std::string label_text_)
 397                 : id (id_)
 398                 , label_text (label_text_)
 399         {}
 400
 401         void as_xml (xmlpp::Element* parent) const;
 402
 403         std::string id;
 404         std::string label_text;
 405 };
 406
 407
 408 class Luminance
 409 {
 410 public:
 411         enum class Unit {
 412                 CANDELA_PER_SQUARE_METRE,
 413                 FOOT_LAMBERT
 414         };
 415
 416         Luminance (cxml::ConstNodePtr node);
 417
 418         Luminance (float value, Unit unit);
 419
 420         void set_value (float v);
 421         void set_unit (Unit u) {
 422                 _unit = u;
 423         }
 424
 425         float value () const {
 426                 return _value;
 427         }
 428
 429         Unit unit () const {
 430                 return _unit;
 431         }
 432
 433         float value_in_foot_lamberts () const;
 434
 435         void as_xml (xmlpp::Element* parent, std::string ns) const;
 436
 437         static std::string unit_to_string (Unit u);
 438         static Unit string_to_unit (std::string u);
 439
 440 private:
 441         float _value;
 442         Unit _unit;
 443 };
 444
 445
 446 bool operator== (Luminance const& a, Luminance const& b);
 447
 448
 449 class MainSoundConfiguration
 450 {
 451 public:
 452         explicit MainSoundConfiguration(std::string);
 453         MainSoundConfiguration (MCASoundField field_, int channels);
 454
 455         MCASoundField field () const {
 456                 return _field;
 457         }
 458
 459         int channels () const {
 460                 return _channels.size();
 461         }
 462
 463         boost::optional<Channel> mapping (int index) const;
 464         void set_mapping (int index, Channel channel);
 465
 466         std::string to_string () const;
 467
 468 private:
 469         MCASoundField _field;
 470         std::vector<boost::optional<Channel>> _channels;
 471 };
 472
 473
 474 }
 475
 476
 477 #endif