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