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