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 enum class Marker {
 353         FFOC, ///< first frame of composition
 354         LFOC, ///< last frame of composition
 355         FFTC, ///< first frame of title credits
 356         LFTC, ///< last frame of title credits
 357         FFOI, ///< first frame of intermission
 358         LFOI, ///< last frame of intermission
 359         FFEC, ///< first frame of end credits
 360         LFEC, ///< last frame of end credits
 361         FFMC, ///< first frame of moving credits
 362         LFMC  ///< last frame of moving credits
 363 };
 364
 365
 366 std::string marker_to_string (Marker);
 367 Marker marker_from_string (std::string);
 368
 369
 370 class Rating
 371 {
 372 public:
 373         Rating (std::string agency_, std::string label_)
 374                 : agency (agency_)
 375                 , label (label_)
 376         {}
 377
 378         explicit Rating (cxml::ConstNodePtr node);
 379
 380         void as_xml (xmlpp::Element* parent) const;
 381
 382         /** URI of the agency issuing the rating */
 383         std::string agency;
 384         /** Rating (e.g. PG, PG-13, 12A etc) */
 385         std::string label;
 386 };
 387
 388
 389 extern bool operator== (Rating const & a, Rating const & b);
 390
 391
 392 enum class Status
 393 {
 394         FINAL, ///< final version
 395         TEMP,  ///< temporary version (picture/sound unfinished)
 396         PRE    ///< pre-release (picture/sound finished)
 397 };
 398
 399
 400 extern std::string status_to_string (Status s);
 401 extern Status string_to_status (std::string s);
 402
 403
 404 class ContentVersion
 405 {
 406 public:
 407         ContentVersion ();
 408
 409         explicit ContentVersion (cxml::ConstNodePtr node);
 410
 411         explicit ContentVersion (std::string label_text_);
 412
 413         ContentVersion (std::string id_, std::string label_text_)
 414                 : id (id_)
 415                 , label_text (label_text_)
 416         {}
 417
 418         void as_xml (xmlpp::Element* parent) const;
 419
 420         std::string id;
 421         std::string label_text;
 422 };
 423
 424
 425 class Luminance
 426 {
 427 public:
 428         enum class Unit {
 429                 CANDELA_PER_SQUARE_METRE,
 430                 FOOT_LAMBERT
 431         };
 432
 433         Luminance (cxml::ConstNodePtr node);
 434
 435         Luminance (float value, Unit unit);
 436
 437         void set_value (float v);
 438         void set_unit (Unit u) {
 439                 _unit = u;
 440         }
 441
 442         float value () const {
 443                 return _value;
 444         }
 445
 446         Unit unit () const {
 447                 return _unit;
 448         }
 449
 450         float value_in_foot_lamberts () const;
 451
 452         void as_xml (xmlpp::Element* parent, std::string ns) const;
 453
 454         static std::string unit_to_string (Unit u);
 455         static Unit string_to_unit (std::string u);
 456
 457 private:
 458         float _value;
 459         Unit _unit;
 460 };
 461
 462
 463 bool operator== (Luminance const& a, Luminance const& b);
 464
 465
 466 class MainSoundConfiguration
 467 {
 468 public:
 469         MainSoundConfiguration (std::string);
 470         MainSoundConfiguration (MCASoundField field_, int channels);
 471
 472         MCASoundField field () const {
 473                 return _field;
 474         }
 475
 476         int channels () const {
 477                 return _channels.size();
 478         }
 479
 480         boost::optional<Channel> mapping (int index) const;
 481         void set_mapping (int index, Channel channel);
 482
 483         std::string to_string () const;
 484
 485 private:
 486         MCASoundField _field;
 487         std::vector<boost::optional<Channel> > _channels;
 488 };
 489
 490
 491 }
 492
 493
 494 #endif