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 };
 124
 125
 126 extern std::string channel_to_mca_id (Channel c, MCASoundField field);
 127 extern Channel mca_id_to_channel (std::string);
 128 extern std::string channel_to_mca_name (Channel c, MCASoundField field);
 129 extern ASDCP::UL channel_to_mca_universal_label (Channel c, MCASoundField field, ASDCP::Dictionary const* dict);
 130
 131
 132 enum class ContentKind
 133 {
 134         FEATURE,
 135         SHORT,
 136         TRAILER,
 137         TEST,
 138         TRANSITIONAL,
 139         RATING,
 140         TEASER,
 141         POLICY,
 142         PUBLIC_SERVICE_ANNOUNCEMENT,
 143         ADVERTISEMENT,
 144         EPISODE,
 145         PROMO
 146 };
 147
 148
 149 extern std::string content_kind_to_string (ContentKind kind);
 150 extern ContentKind content_kind_from_string (std::string kind);
 151
 152
 153 enum class Effect
 154 {
 155         NONE,
 156         BORDER,
 157         SHADOW
 158 };
 159
 160
 161 extern std::string effect_to_string (Effect e);
 162 extern Effect string_to_effect (std::string s);
 163
 164
 165 enum class HAlign
 166 {
 167         LEFT,   ///< horizontal position is distance from left of screen to left of subtitle
 168         CENTER, ///< horizontal position is distance from centre of screen to centre of subtitle
 169         RIGHT,  ///< horizontal position is distance from right of screen to right of subtitle
 170 };
 171
 172
 173 extern std::string halign_to_string (HAlign a);
 174 extern HAlign string_to_halign (std::string s);
 175
 176
 177 enum class VAlign
 178 {
 179         TOP,    ///< vertical position is distance from top of screen to top of subtitle
 180         CENTER, ///< vertical position is distance from centre of screen to centre of subtitle
 181         BOTTOM  ///< vertical position is distance from bottom of screen to bottom of subtitle
 182 };
 183
 184
 185 extern std::string valign_to_string (VAlign a);
 186 extern VAlign string_to_valign (std::string s);
 187
 188
 189 /** Direction for subtitle test */
 190 enum class Direction
 191 {
 192         LTR, ///< left-to-right
 193         RTL, ///< right-to-left
 194         TTB, ///< top-to-bottom
 195         BTT  ///< bottom-to-top
 196 };
 197
 198
 199 extern std::string direction_to_string (Direction a);
 200 extern Direction string_to_direction (std::string s);
 201
 202
 203 enum class Eye
 204 {
 205         LEFT,
 206         RIGHT
 207 };
 208
 209
 210 /** @class Fraction
 211  *  @brief A fraction (i.e. a thing with an integer numerator and an integer denominator).
 212  */
 213 class Fraction
 214 {
 215 public:
 216         /** Construct a fraction of 0/0 */
 217         Fraction () {}
 218         explicit Fraction (std::string s);
 219         /** Construct a fraction with a specified numerator and denominator.
 220          *  @param n Numerator.
 221          *  @param d Denominator.
 222          */
 223         Fraction (int n, int d) : numerator (n), denominator (d) {}
 224
 225         float as_float () const {
 226                 return float (numerator) / denominator;
 227         }
 228
 229         std::string as_string () const;
 230
 231         int numerator = 0;
 232         int denominator = 0;
 233 };
 234
 235
 236 extern bool operator== (Fraction const & a, Fraction const & b);
 237 extern bool operator!= (Fraction const & a, Fraction const & b);
 238
 239
 240 /** @struct EqualityOptions
 241  *  @brief  A class to describe what "equality" means for a particular test.
 242  *
 243  *  When comparing things, we want to be able to ignore some differences;
 244  *  this class expresses those differences.
 245  *
 246  *  It also contains some settings for how the comparison should be done.
 247  */
 248 struct EqualityOptions
 249 {
 250         /** Construct an EqualityOptions where nothing at all can differ */
 251         EqualityOptions () {}
 252
 253         /** The maximum allowable mean difference in pixel value between two images */
 254         double max_mean_pixel_error = 0;
 255         /** The maximum standard deviation of the differences in pixel value between two images */
 256         double max_std_dev_pixel_error = 0;
 257         /** The maximum difference in audio sample value between two soundtracks */
 258         int max_audio_sample_error = 0;
 259         /** true if the &lt;AnnotationText&gt; nodes of CPLs are allowed to differ */
 260         bool cpl_annotation_texts_can_differ = false;
 261         /** true if the &lt;AnnotationText&gt; nodes of Reels are allowed to differ */
 262         bool reel_annotation_texts_can_differ = false;
 263         /** true if <Hash>es in Reels can differ */
 264         bool reel_hashes_can_differ = false;
 265         /** true if IssueDate nodes can differ */
 266         bool issue_dates_can_differ = false;
 267         bool load_font_nodes_can_differ = false;
 268         bool keep_going = false;
 269         /** true to save the first pair of differeng image subtitles to the current working directory */
 270         bool export_differing_subtitles = false;
 271 };
 272
 273
 274 enum class NoteType {
 275         PROGRESS,
 276         ERROR,
 277         NOTE
 278 };
 279
 280
 281 enum class Standard {
 282         INTEROP,
 283         SMPTE
 284 };
 285
 286
 287 enum class Formulation {
 288         MODIFIED_TRANSITIONAL_1,
 289         MULTIPLE_MODIFIED_TRANSITIONAL_1,
 290         DCI_ANY,
 291         DCI_SPECIFIC,
 292         /** For testing: adds no AuthorizedDeviceInfo tag */
 293         MODIFIED_TRANSITIONAL_TEST
 294 };
 295
 296
 297 /** @class Colour
 298  *  @brief An RGB colour
 299  */
 300 class Colour
 301 {
 302 public:
 303         /** Construct a Colour, initialising it to black */
 304         Colour ();
 305
 306         /** Construct a Colour from R, G and B.  The values run between
 307          *  0 and 255.
 308          */
 309         Colour (int r_, int g_, int b_);
 310
 311         /** Construct a Colour from an ARGB hex string; the alpha value is ignored.
 312          *  @param argb_hex A string of the form AARRGGBB, where e.g. RR is a two-character
 313          *  hex value.
 314          */
 315         explicit Colour (std::string argb_hex);
 316
 317         int r = 0; ///< red component, from 0 to 255
 318         int g = 0; ///< green component, from 0 to 255
 319         int b = 0; ///< blue component, from 0 to 255
 320
 321         /** @return An RGB string of the form RRGGBB, where e.g. RR is a two-character
 322          *  hex value.
 323          */
 324         std::string to_rgb_string () const;
 325
 326         /** @return An ARGB string of the form AARRGGBB, where e.g. RR is a two-character
 327          *  hex value.  The alpha value will always be FF (ie 255; maximum alpha).
 328          */
 329         std::string to_argb_string () const;
 330 };
 331
 332
 333 extern bool operator== (Colour const & a, Colour const & b);
 334 extern bool operator!= (Colour const & a, Colour const & b);
 335
 336
 337 typedef boost::function<void (NoteType, std::string)> NoteHandler;
 338
 339
 340 /** Maximum absolute difference between dcp::SubtitleString::aspect_adjust values that
 341  *  are considered equal
 342  */
 343 constexpr float ASPECT_ADJUST_EPSILON = 1e-3;
 344
 345
 346 /** Maximum absolute difference between dcp::SubtitleString alignment values that
 347  *  are considered equal.
 348  */
 349 constexpr float ALIGN_EPSILON = 1e-3;
 350
 351
 352 /** Maximum absolute difference between dcp::SubtitleString space_before values that
 353  *  are considered equal.
 354  */
 355 constexpr float SPACE_BEFORE_EPSILON = 1e-3;
 356
 357
 358 enum class Marker {
 359         FFOC, ///< first frame of composition
 360         LFOC, ///< last frame of composition
 361         FFTC, ///< first frame of title credits
 362         LFTC, ///< last frame of title credits
 363         FFOI, ///< first frame of intermission
 364         LFOI, ///< last frame of intermission
 365         FFEC, ///< first frame of end credits
 366         LFEC, ///< last frame of end credits
 367         FFMC, ///< first frame of moving credits
 368         LFMC  ///< last frame of moving credits
 369 };
 370
 371
 372 std::string marker_to_string (Marker);
 373 Marker marker_from_string (std::string);
 374
 375
 376 class Rating
 377 {
 378 public:
 379         Rating (std::string agency_, std::string label_)
 380                 : agency (agency_)
 381                 , label (label_)
 382         {}
 383
 384         explicit Rating (cxml::ConstNodePtr node);
 385
 386         void as_xml (xmlpp::Element* parent) const;
 387
 388         /** URI of the agency issuing the rating */
 389         std::string agency;
 390         /** Rating (e.g. PG, PG-13, 12A etc) */
 391         std::string label;
 392 };
 393
 394
 395 extern bool operator== (Rating const & a, Rating const & b);
 396
 397
 398 enum class Status
 399 {
 400         FINAL, ///< final version
 401         TEMP,  ///< temporary version (picture/sound unfinished)
 402         PRE    ///< pre-release (picture/sound finished)
 403 };
 404
 405
 406 extern std::string status_to_string (Status s);
 407 extern Status string_to_status (std::string s);
 408
 409
 410 class ContentVersion
 411 {
 412 public:
 413         ContentVersion ();
 414
 415         explicit ContentVersion (cxml::ConstNodePtr node);
 416
 417         explicit ContentVersion (std::string label_text_);
 418
 419         ContentVersion (std::string id_, std::string label_text_)
 420                 : id (id_)
 421                 , label_text (label_text_)
 422         {}
 423
 424         void as_xml (xmlpp::Element* parent) const;
 425
 426         std::string id;
 427         std::string label_text;
 428 };
 429
 430
 431 class Luminance
 432 {
 433 public:
 434         enum class Unit {
 435                 CANDELA_PER_SQUARE_METRE,
 436                 FOOT_LAMBERT
 437         };
 438
 439         Luminance (cxml::ConstNodePtr node);
 440
 441         Luminance (float value, Unit unit);
 442
 443         void set_value (float v);
 444         void set_unit (Unit u) {
 445                 _unit = u;
 446         }
 447
 448         float value () const {
 449                 return _value;
 450         }
 451
 452         Unit unit () const {
 453                 return _unit;
 454         }
 455
 456         float value_in_foot_lamberts () const;
 457
 458         void as_xml (xmlpp::Element* parent, std::string ns) const;
 459
 460         static std::string unit_to_string (Unit u);
 461         static Unit string_to_unit (std::string u);
 462
 463 private:
 464         float _value;
 465         Unit _unit;
 466 };
 467
 468
 469 bool operator== (Luminance const& a, Luminance const& b);
 470
 471
 472 class MainSoundConfiguration
 473 {
 474 public:
 475         MainSoundConfiguration (std::string);
 476         MainSoundConfiguration (MCASoundField field_, int channels);
 477
 478         MCASoundField field () const {
 479                 return _field;
 480         }
 481
 482         int channels () const {
 483                 return _channels.size();
 484         }
 485
 486         boost::optional<Channel> mapping (int index) const;
 487         void set_mapping (int index, Channel channel);
 488
 489         std::string to_string () const;
 490
 491 private:
 492         MCASoundField _field;
 493         std::vector<boost::optional<Channel>> _channels;
 494 };
 495
 496
 497 }
 498
 499
 500 #endif