Source: lib/cea/cea708_window.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.cea.Cea708Window');
  9. goog.require('shaka.cea.CeaUtils');
  10. goog.require('shaka.cea.CeaUtils.StyledChar');
  11. goog.require('shaka.text.Cue');
  12. goog.require('shaka.text.CueRegion');
  15. /**
  16.  * CEA-708 Window. Each CEA-708 service owns 8 of these.
  17.  */
  18. shaka.cea.Cea708Window = class {
  19.   /**
  20.    * @param {number} windowNum
  21.    */
  22.   constructor(windowNum, parentService) {
  23.     /**
  24.      * Number for the parent service (1 - 63).
  25.      * @private {number}
  26.      */
  27.     this.parentService_ = parentService;
  29.     /**
  30.      * A number from 0 - 7 indicating the window number in the
  31.      * service that owns this window.
  32.      * @private {number}
  33.      */
  34.     this.windowNum_ = windowNum;
  36.     /**
  37.      * Indicates whether this window is visible.
  38.      * @private {boolean}
  39.      */
  40.     this.visible_ = false;
  42.     /**
  43.      * Indicates whether the horizontal and vertical anchors coordinates specify
  44.      * a percentage of the screen, or physical coordinates on the screen.
  45.      * @private {boolean}
  46.      */
  47.     this.relativeToggle_ = false;
  49.     /**
  50.      * Horizontal anchor. Loosely corresponds to a WebVTT viewport X anchor.
  51.      * @private {number}
  52.      */
  53.     this.horizontalAnchor_ = 0;
  55.     /**
  56.      * Vertical anchor. Loosely corresponds to a WebVTT viewport Y anchor.
  57.      * @private {number}
  58.      */
  59.     this.verticalAnchor_ = 0;
  61.     /**
  62.      * If valid, ranges from 0 to 8, specifying one of 9 locations on window:
  63.      * 0________1________2
  64.      * |        |        |
  65.      * 3________4________5
  66.      * |        |        |
  67.      * 6________7________8
  68.      * Diagram is valid as per CEA-708-E section 8.4.4.
  69.      * Each of these locations corresponds to a WebVTT region's "region anchor".
  70.      * @private {number}
  71.      */
  72.     this.anchorId_ = 0;
  74.     /**
  75.      * Indicates the number of rows in this window's buffer/memory.
  76.      * @private {number}
  77.      */
  78.     this.rowCount_ = 0;
  80.     /**
  81.      * Indicates the number of columns in this window's buffer/memory.
  82.      * @private {number}
  83.      */
  84.     this.colCount_ = 0;
  86.     /**
  87.      * Center by default.
  88.      * @private {!shaka.cea.Cea708Window.TextJustification}
  89.      */
  90.     this.justification_ = shaka.cea.Cea708Window.TextJustification.CENTER;
  92.     /**
  93.      * An array of rows of styled characters, representing the
  94.      * current text and styling of text in this window.
  95.      * @private {!Array<!Array<?shaka.cea.CeaUtils.StyledChar>>}
  96.      */
  97.     this.memory_ = [];
  99.     /**
  100.      * @private {number}
  101.      */
  102.     this.startTime_ = 0;
  104.     /**
  105.      * Row that the current pen is pointing at.
  106.      * @private {number}
  107.      */
  108.     this.row_ = 0;
  110.     /**
  111.      * Column that the current pen is pointing at.
  112.      * @private {number}
  113.      */
  114.     this.col_ = 0;
  116.     /**
  117.      * Indicates whether the current pen position is italicized.
  118.      * @private {boolean}
  119.      */
  120.     this.italics_ = false;
  122.     /**
  123.      * Indicates whether the current pen position is underlined.
  124.      * @private {boolean}
  125.      */
  126.     this.underline_ = false;
  128.     /**
  129.      * Indicates the text color at the current pen position.
  130.      * @private {string}
  131.      */
  132.     this.textColor_ = shaka.cea.CeaUtils.DEFAULT_TXT_COLOR;
  134.     /**
  135.      * Indicates the background color at the current pen position.
  136.      * @private {string}
  137.      */
  138.     this.backgroundColor_ = shaka.cea.CeaUtils.DEFAULT_BG_COLOR;
  140.     this.resetMemory();
  141.   }
  143.   /**
  144.    * @param {boolean} visible
  145.    * @param {number} verticalAnchor
  146.    * @param {number} horizontalAnchor
  147.    * @param {number} anchorId
  148.    * @param {boolean} relativeToggle
  149.    * @param {number} rowCount
  150.    * @param {number} colCount
  151.    */
  152.   defineWindow(visible, verticalAnchor, horizontalAnchor, anchorId,
  153.       relativeToggle, rowCount, colCount) {
  154.     this.visible_ = visible;
  155.     this.verticalAnchor_ = verticalAnchor;
  156.     this.horizontalAnchor_ = horizontalAnchor;
  157.     this.anchorId_ = anchorId;
  158.     this.relativeToggle_ = relativeToggle;
  159.     this.rowCount_ = rowCount;
  160.     this.colCount_ = colCount;
  161.   }
  163.   /**
  164.    * Resets the memory buffer.
  165.    */
  166.   resetMemory() {
  167.     this.memory_ = [];
  168.     for (let i = 0; i < shaka.cea.Cea708Window.MAX_ROWS; i++) {
  169.       this.memory_.push(this.createNewRow_());
  170.     }
  171.   }
  173.   /**
  174.    * Allocates and returns a new row.
  175.    * @return {!Array<?shaka.cea.CeaUtils.StyledChar>}
  176.    * @private
  177.    */
  178.   createNewRow_() {
  179.     const row = [];
  180.     for (let j = 0; j < shaka.cea.Cea708Window.MAX_COLS; j++) {
  181.       row.push(null);
  182.     }
  183.     return row;
  184.   }
  186.   /**
  187.    * Sets the unicode value for a char at the current pen location.
  188.    * @param {string} char
  189.    */
  190.   setCharacter(char) {
  191.     // Check if the pen is out of bounds.
  192.     if (!this.isPenInBounds_()) {
  193.       return;
  194.     }
  196.     const cea708Char = new shaka.cea.CeaUtils.StyledChar(
  197.         char, this.underline_, this.italics_,
  198.         this.backgroundColor_, this.textColor_);
  199.     this.memory_[this.row_][this.col_] = cea708Char;
  201.     // Increment column
  202.     this.col_ ++;
  203.   }
  205.   /**
  206.    * Erases a character from the buffer and moves the pen back.
  207.    */
  208.   backspace() {
  209.     if (!this.isPenInBounds_()) {
  210.       return;
  211.     }
  213.     // Check if a backspace can be done.
  214.     if (this.col_ <= 0 && this.row_ <= 0) {
  215.       return;
  216.     }
  218.     if (this.col_ <= 0) {
  219.       // Move pen back a row.
  220.       this.col_ = this.colCount_ - 1;
  221.       this.row_--;
  222.     } else {
  223.       // Move pen back a column.
  224.       this.col_--;
  225.     }
  227.     // Erase the character occupied at that position.
  228.     this.memory_[this.row_][this.col_] = null;
  229.   }
  231.   /**
  232.    * @private
  233.    */
  234.   isPenInBounds_() {
  235.     const inRowBounds = this.row_ < this.rowCount_ && this.row_ >= 0;
  236.     const inColBounds = this.col_ < this.colCount_ && this.col_ >= 0;
  237.     return inRowBounds && inColBounds;
  238.   }
  240.   /**
  241.    * @return {boolean}
  242.    */
  243.   isVisible() {
  244.     return this.visible_;
  245.   }
  247.   /**
  248.    * Moves up <count> rows in the buffer.
  249.    * @param {number} count
  250.    * @private
  251.    */
  252.   moveUpRows_(count) {
  253.     let dst = 0; // Row each row should be moved to.
  255.     // Move existing rows up by <count>.
  256.     for (let i = count; i < shaka.cea.Cea708Window.MAX_ROWS; i++, dst++) {
  257.       this.memory_[dst] = this.memory_[i];
  258.     }
  260.     // Create <count> new rows at the bottom.
  261.     for (let i = 0; i < count; i++, dst++) {
  262.       this.memory_[dst] = this.createNewRow_();
  263.     }
  264.   }
  266.   /**
  267.    * Handles CR. Increments row - if last row, "roll up" all rows by one.
  268.    */
  269.   carriageReturn() {
  270.     if (this.row_ + 1 >= this.rowCount_) {
  271.       this.moveUpRows_(1);
  272.       this.col_ = 0;
  273.       return;
  274.     }
  276.     this.row_++;
  277.     this.col_ = 0;
  278.   }
  280.   /**
  281.    * Handles HCR. Moves the pen to the beginning of the cur. row and clears it.
  282.    */
  283.   horizontalCarriageReturn() {
  284.     this.memory_[this.row_] = this.createNewRow_();
  285.     this.col_ = 0;
  286.   }
  288.   /**
  289.    * @param {number} endTime
  290.    * @param {number} serviceNumber Number of the service emitting this caption.
  291.    * @return {?shaka.extern.ICaptionDecoder.ClosedCaption}
  292.    */
  293.   forceEmit(endTime, serviceNumber) {
  294.     const stream = `svc${serviceNumber}`;
  295.     const TextJustification = shaka.cea.Cea708Window.TextJustification;
  296.     const topLevelCue = new shaka.text.Cue(
  297.         this.startTime_, endTime, /* payload= */ '');
  299.     if (this.justification_ === TextJustification.LEFT) {
  300.       // LEFT justified.
  301.       topLevelCue.textAlign = shaka.text.Cue.textAlign.LEFT;
  302.     } else if (this.justification_ === TextJustification.RIGHT) {
  303.       // RIGHT justified.
  304.       topLevelCue.textAlign = shaka.text.Cue.textAlign.RIGHT;
  305.     } else {
  306.       // CENTER justified. Both FULL and CENTER are handled as CENTER justified.
  307.       topLevelCue.textAlign = shaka.text.Cue.textAlign.CENTER;
  308.     }
  310.     this.adjustRegion_(topLevelCue.region);
  312.     const caption = shaka.cea.CeaUtils.getParsedCaption(
  313.         topLevelCue, stream, this.memory_, this.startTime_, endTime);
  314.     if (caption) {
  315.       // If a caption is being emitted, then the next caption's start time
  316.       // should be no less than this caption's end time.
  317.       this.setStartTime(endTime);
  318.     }
  319.     return caption;
  320.   }
  322.   /**
  323.    * @param {number} row
  324.    * @param {number} col
  325.    */
  326.   setPenLocation(row, col) {
  327.     this.row_ = row;
  328.     this.col_ = col;
  329.   }
  331.   /**
  332.    * @param {string} backgroundColor
  333.    */
  334.   setPenBackgroundColor(backgroundColor) {
  335.     this.backgroundColor_ = backgroundColor;
  336.   }
  338.   /**
  339.    * @param {string} textColor
  340.    */
  341.   setPenTextColor(textColor) {
  342.     this.textColor_ = textColor;
  343.   }
  345.   /**
  346.    * @param {boolean} underline
  347.    */
  348.   setPenUnderline(underline) {
  349.     this.underline_ = underline;
  350.   }
  352.   /**
  353.    * @param {boolean} italics
  354.    */
  355.   setPenItalics(italics) {
  356.     this.italics_ = italics;
  357.   }
  359.   /** Reset the pen to 0,0 with default styling. */
  360.   resetPen() {
  361.     this.row_ = 0;
  362.     this.col_ = 0;
  363.     this.underline_ = false;
  364.     this.italics_ = false;
  365.     this.textColor_ = shaka.cea.CeaUtils.DEFAULT_TXT_COLOR;
  366.     this.backgroundColor_ = shaka.cea.CeaUtils.DEFAULT_BG_COLOR;
  367.   }
  369.   /**
  370.    * @param {!shaka.cea.Cea708Window.TextJustification} justification
  371.    */
  372.   setJustification(justification) {
  373.     this.justification_ = justification;
  374.   }
  376.   /**
  377.    * Sets the window to visible.
  378.    */
  379.   display() {
  380.     this.visible_ = true;
  381.   }
  383.   /**
  384.    * Sets the window to invisible.
  385.    */
  386.   hide() {
  387.     this.visible_ = false;
  388.   }
  390.   /**
  391.    * Toggles the visibility of the window.
  392.    */
  393.   toggle() {
  394.     this.visible_ = !this.visible_;
  395.   }
  397.   /**
  398.    * Sets the start time for the cue to be emitted.
  399.    * @param {number} pts
  400.    */
  401.   setStartTime(pts) {
  402.     this.startTime_ = pts;
  403.   }
  405.   /**
  406.    * Support window positioning by mapping anchor related values to CueRegion.
  407.    * https://dvcs.w3.org/hg/text-tracks/raw-file/default/608toVTT/608toVTT.html#positioning-in-cea-708
  408.    * @param {shaka.text.CueRegion} region
  409.    * @private
  410.    */
  411.   adjustRegion_(region) {
  412.     if (this.parentService_) {
  413.       region.id += 'svc' + this.parentService_;
  414.     }
  415.     region.id += 'win' + this.windowNum_;
  417.     region.height = this.rowCount_;
  418.     region.width = this.colCount_;
  419.     region.heightUnits = shaka.text.CueRegion.units.LINES;
  420.     region.widthUnits = shaka.text.CueRegion.units.LINES;
  422.     region.viewportAnchorX = this.horizontalAnchor_;
  423.     region.viewportAnchorY = this.verticalAnchor_;
  424.     // WebVTT's region viewport anchors are technically always in percentages.
  425.     // However, we don't know the aspect ratio of the video at this point,
  426.     // which determines how we interpret the horizontal anchor.
  427.     // So, we expose the additonal flag to reflect whether these viewport anchor
  428.     // values can be used be used as is or should be converted to percentages.
  429.     region.viewportAnchorUnits = this.relativeToggle_ ?
  430.       shaka.text.CueRegion.units.PERCENTAGE : shaka.text.CueRegion.units.LINES;
  432.     const AnchorId = shaka.cea.Cea708Window.AnchorId;
  434.     switch (this.anchorId_) {
  435.       case AnchorId.UPPER_LEFT:
  436.         region.regionAnchorX = 0;
  437.         region.regionAnchorY = 0;
  438.         break;
  439.       case AnchorId.UPPER_CENTER:
  440.         region.regionAnchorX = 50;
  441.         region.regionAnchorY = 0;
  442.         break;
  443.       case AnchorId.UPPER_RIGHT:
  444.         region.regionAnchorX = 100;
  445.         region.regionAnchorY = 0;
  446.         break;
  447.       case AnchorId.MIDDLE_LEFT:
  448.         region.regionAnchorX = 0;
  449.         region.regionAnchorY = 50;
  450.         break;
  451.       case AnchorId.MIDDLE_CENTER:
  452.         region.regionAnchorX = 50;
  453.         region.regionAnchorY = 50;
  454.         break;
  455.       case AnchorId.MIDDLE_RIGHT:
  456.         region.regionAnchorX = 100;
  457.         region.regionAnchorY = 50;
  458.         break;
  459.       case AnchorId.LOWER_LEFT:
  460.         region.regionAnchorX = 0;
  461.         region.regionAnchorY = 100;
  462.         break;
  463.       case AnchorId.LOWER_CENTER:
  464.         region.regionAnchorX = 50;
  465.         region.regionAnchorY = 100;
  466.         break;
  467.       case AnchorId.LOWER_RIGHT:
  468.         region.regionAnchorX = 100;
  469.         region.regionAnchorY = 100;
  470.         break;
  471.     }
  472.   }
  473. };
  475. /**
  476.  * Caption type.
  477.  * @const @enum {number}
  478.  */
  479. shaka.cea.Cea708Window.TextJustification = {
  480.   LEFT: 0,
  481.   RIGHT: 1,
  482.   CENTER: 2,
  483.   FULL: 3,
  484. };
  486. /**
  487.  * Possible AnchorId values.
  488.  * @const @enum {number}
  489.  */
  490. shaka.cea.Cea708Window.AnchorId = {
  491.   UPPER_LEFT: 0,
  492.   UPPER_CENTER: 1,
  493.   UPPER_RIGHT: 2,
  494.   MIDDLE_LEFT: 3,
  495.   MIDDLE_CENTER: 4,
  496.   MIDDLE_RIGHT: 5,
  497.   LOWER_LEFT: 6,
  498.   LOWER_CENTER: 7,
  499.   LOWER_RIGHT: 8,
  500. };
  502. /**
  503.  * Can be indexed 0-31 for 4:3 format, and 0-41 for 16:9 formats.
  504.  * Thus the absolute maximum is 42 columns for the 16:9 format.
  505.  * @private @const {number}
  506.  */
  507. shaka.cea.Cea708Window.MAX_COLS = 42;
  509. /**
  510.  * Maximum of 16 rows that can be indexed from 0 to 15.
  511.  * @private @const {number}
  512.  */
  513. shaka.cea.Cea708Window.MAX_ROWS = 16;