Introduce custom resolutions

docs/api/resolution.md

@@ -4,17 +4,18 @@ A `Resolution` is a setting defined by a string. It is mapped to a size measured
 
 The table below shows examples of how resolution strings are converted to pixels:
 
-| Resolution | 16:9 | 16:10 | 4:3 | Notes |
-| ---------- | ---- | ----- | --- | ----- |
-| `"xs"` | 214x120 | 192x120 | 160x120 | |
-| `"xs+"` | 256x144 | 230x144 | 192x144 | 144p |
-| `"sm"` | 426x240 | 384x240 | 320x240 | 240p |
-| `"sm+"` | 512x288 | 460x288 | 384x288 | |
-| `"md"` | 568x320 | 512x320 | 426x320 | |
-| `"md+"` | 640x360 | 576x360 | 480x360 | 360p |
-| `"lg"` | 854x480 | 768x480 | 640x480 | 480p |
-| `"lg+"` | 1066x600 | 960x600 | 800x600 | |
-| `"xl"` | 1280x720 | 1152x720 | 960x720 | 720p |
-| `"xl+"` | 1366x768 | 1228x768 | 1024x768 | |
-| `"xxl"` | 1600x900 | 1440x900 | 1200x900 | |
-| `"xxl+"` | 1706x960 | 1536x960 | 1280x960 | |
+| Resolution | Alias | 16:9 | 16:10 | 4:3 | Notes |
+| ---------- | ----- | ---- | ----- | --- | ----- |
+| `"120p"` | `"xs"` | 214x120 | 192x120 | 160x120 | |
+| `"144p"` | `"xs+"` | 256x144 | 230x144 | 192x144 | |
+| `"240p"` | `"sm"` | 426x240 | 384x240 | 320x240 | SD |
+| `"288p"` | `"sm+"` | 512x288 | 460x288 | 384x288 | |
+| `"320p"` | `"md"` | 568x320 | 512x320 | 426x320 | |
+| `"360p"` | `"md+"` | 640x360 | 576x360 | 480x360 | SD |
+| `"480p"` | `"lg"` | 854x480 | 768x480 | 640x480 | SD |
+| `"600p"` | `"lg+"` | 1066x600 | 960x600 | 800x600 | |
+| `"720p"` | `"xl"` | 1280x720 | 1152x720 | 960x720 | HD |
+| `"768p"` | `"xl+"` | 1366x768 | 1228x768 | 1024x768 | |
+| `"900p"` | `"xxl"` | 1600x900 | 1440x900 | 1200x900 | |
+| `"960p"` | `"xxl+"` | 1706x960 | 1536x960 | 1280x960 | |
+| `"1080p"` | | 1920x1080 | 1728x1080 | 1440x1080 | Full HD |

src/utils/resolution.ts

@@ -24,11 +24,21 @@ import Speedy from 'speedy-vision';
 import { SpeedySize } from 'speedy-vision/types/core/speedy-size';
 import { IllegalArgumentError } from './errors';
 
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type EvenDigit = '0' | '2' | '4' | '6' | '8';
+type PositiveDigit = '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type OptionalDigit = Digit | '';
+type CustomResolution = `${PositiveDigit}${OptionalDigit}${Digit}${EvenDigit}p`;
+type ResolutionAlias = 'xs' | 'xs+' | 'sm' | 'sm+' | 'md' | 'md+' | 'lg' | 'lg+' | 'xl' | 'xl+' | 'xxl' | 'xxl+';
+
 /** Resolution type */
-export type Resolution = 'xs' | 'xs+' | 'sm' | 'sm+' | 'md' | 'md+' | 'lg' | 'lg+' | 'xl' | 'xl+' | 'xxl' | 'xxl+';
+export type Resolution = ResolutionAlias | CustomResolution;
+
+/** A regex that identifies custom resolutions */
+const CUSTOM_RESOLUTION_REGEX = /^[1-9][0-9]?[0-9][02468]p$/;
 
-/** Reference heights when in landscape mode, measured in pixels */
-const REFERENCE_HEIGHT: { readonly [R in Resolution]: number } = {
+/** Reference heights when in landscape mode, measured in pixels, for all aliases */
+const ALIAS_TO_HEIGHT: { readonly [R in ResolutionAlias]: number } = {
     'xs' : 120,
     'xs+': 144,
     'sm' : 240,
@@ -44,7 +54,6 @@ const REFERENCE_HEIGHT: { readonly [R in Resolution]: number } = {
     //'ul-': 1024,
     //'ul': 1080, // what should we call this? xxxl? ul? (ultra large?)
     //'ul+': 1200,
-    // instead of defining xxxl, what if we accept custom resolution names such as "720p" and "1080p"?
 };
 
 /**
@@ -55,10 +64,10 @@ const REFERENCE_HEIGHT: { readonly [R in Resolution]: number } = {
  */
 export function computeResolution(resolution: Resolution, aspectRatio: number): SpeedySize
 {
-    const referenceHeight = REFERENCE_HEIGHT[resolution];
+    const referenceHeight = parseHeight(resolution);
     let width = 0, height = 0;
 
-    if(referenceHeight === undefined)
+    if(Number.isNaN(referenceHeight))
         throw new IllegalArgumentError('Invalid resolution: ' + resolution);
     else if(aspectRatio <= 0)
         throw new IllegalArgumentError('Invalid aspect ratio: ' + aspectRatio);
@@ -77,4 +86,20 @@ export function computeResolution(resolution: Resolution, aspectRatio: number):
     }
 
     return Speedy.Size(width, height);
+}
+
+/**
+ * Get the height in pixels of a resolution
+ * @param resolution resolution type
+ * @returns the height in pixels, or NaN on error
+ */
+function parseHeight(resolution: Resolution): number
+{
+    if(ALIAS_TO_HEIGHT.hasOwnProperty(resolution))
+        return ALIAS_TO_HEIGHT[resolution as ResolutionAlias];
+
+    if(CUSTOM_RESOLUTION_REGEX.test(resolution))
+        return parseInt(resolution);
+
+    return Number.NaN;
 }