web: Add letterbox config option

Cargo.lock

@@ -2998,6 +2998,7 @@ dependencies = [
  "quick-xml",
  "rand",
  "ruffle_macros",
+ "serde",
  "smallvec",
  "swf",
  "thiserror",
@@ -3132,6 +3133,7 @@ dependencies = [
  "ruffle_render_canvas",
  "ruffle_render_webgl",
  "ruffle_web_common",
+ "serde",
  "url 2.2.0",
  "wasm-bindgen",
  "wasm-bindgen-futures",
@@ -3269,6 +3271,17 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_json"
+version = "1.0.61"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fceb2595057b6891a4ee808f70054bd2d12f0e97f1cbb78689b59f676df325a"
+dependencies = [
+ "itoa",
+ "ryu",
+ "serde",
+]
+
 [[package]]
 name = "shlex"
 version = "0.1.1"
@@ -3820,6 +3833,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3cd364751395ca0f68cafb17666eee36b63077fb5ecd972bbcd74c90c4bf736e"
 dependencies = [
  "cfg-if 1.0.0",
+ "serde",
+ "serde_json",
  "wasm-bindgen-macro",
 ]
 

core/Cargo.toml

@@ -35,6 +35,7 @@ num-traits = "0.2"
 instant = "0.1"
 encoding_rs = "0.8.26"
 rand = { version = "0.8.1", features = ["std", "small_rng"], default-features = false }
+serde = { version = "1.0.118", features = ["derive"], optional = true }
 
 [dependencies.jpeg-decoder]
 version = "0.1.20"
@@ -45,7 +46,7 @@ approx = "0.4.0"
 pretty_assertions = "0.6.1"
 
 [features]
-default = ["minimp3"]
+default = ["minimp3", "serde"]
 lzma = ["swf/lzma"]
 wasm-bindgen = [ "instant/wasm-bindgen" ]
 avm_debug = []

core/src/player.rs

@@ -27,6 +27,8 @@ use gc_arena::{make_arena, ArenaParameters, Collect, GcCell};
 use instant::Instant;
 use log::info;
 use rand::{rngs::SmallRng, SeedableRng};
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Serialize};
 use std::collections::{BTreeMap, HashMap};
 use std::convert::TryFrom;
 use std::ops::DerefMut;
@@ -1403,8 +1405,21 @@ unsafe impl<'gc> gc_arena::Collect for DragObject<'gc> {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[cfg_attr(feature = "serde", serde(rename = "letterbox"))]
 pub enum Letterbox {
+    #[cfg_attr(feature = "serde", serde(rename = "off"))]
     Off,
+
+    #[cfg_attr(feature = "serde", serde(rename = "fullscreen"))]
     Fullscreen,
+
+    #[cfg_attr(feature = "serde", serde(rename = "on"))]
     On,
 }
+
+impl Default for Letterbox {
+    fn default() -> Self {
+        Letterbox::Fullscreen
+    }
+}

web/Cargo.toml

@@ -32,15 +32,16 @@ ruffle_render_canvas = { path = "../render/canvas", optional = true }
 ruffle_web_common = { path = "common" }
 ruffle_render_webgl = { path = "../render/webgl", optional = true }
 url = "2.2.0"
-wasm-bindgen = "0.2.69"
+wasm-bindgen = { version = "0.2.69", features = ["serde-serialize"] }
 wasm-bindgen-futures = "0.4.19"
 chrono = { version = "0.4", features = ["wasmbind"] }
 getrandom = { version = "0.2", features = ["js"] }
+serde = { version = "1.0.118", features = ["derive"] }
 
 [dependencies.ruffle_core]
 path = "../core"
 default-features = false
-features = ["puremp3", "wasm-bindgen"]
+features = ["puremp3", "serde", "wasm-bindgen"]
 
 [dependencies.web-sys]
 version = "0.3.45"

web/packages/core/src/load-options.ts

@@ -25,6 +25,30 @@ export enum AutoPlay {
     Auto = "auto",
 }
 
+/**
+ * Controls whether the content is letterboxed or pillarboxed when the
+ * player's aspect ratio does not match the movie's aspect ratio.
+ *
+ * When letterboxed, black bars will be rendered around the exterior
+ * margins of the content.
+ */
+export enum Letterbox {
+    /**
+     * The content will never be letterboxed.
+     */
+    Off = "off",
+
+    /**
+     * The content will only be letterboxed if the content is running fullscreen.
+     */
+    Fullscreen = "fullscreen",
+
+    /**
+     * The content will always be letterboxed.
+     */
+    On = "on",
+}
+
 /**
  * When the player is muted, this controls whether or not Ruffle will show a
  * "click to unmute" overlay on top of the movie.
@@ -62,6 +86,14 @@ export interface BaseLoadOptions {
      */
     autoplay?: AutoPlay;
 
+    /**
+     * Controls letterbox behavior when the Flash container size does not
+     * match the movie size.
+     *
+     * @default Letterbox.Fullscreen
+     */
+    letterbox?: Letterbox;
+
     /**
      * Controls the visibility of the unmute overlay when the player
      * is started muted.

web/packages/core/src/ruffle-player.ts

@@ -317,7 +317,8 @@ export class RufflePlayer extends HTMLElement {
             this,
             this.allowScriptAccess,
             config.upgradeToHttps !== false &&
-                window.location.protocol === "https:"
+                window.location.protocol === "https:",
+            config
         );
         console.log("New Ruffle instance created.");
 

web/src/lib.rs

@@ -28,8 +28,9 @@ use ruffle_core::external::{
 };
 use ruffle_core::property_map::PropertyMap;
 use ruffle_core::tag_utils::SwfMovie;
-use ruffle_core::PlayerEvent;
+use ruffle_core::{Letterbox, PlayerEvent};
 use ruffle_web_common::JsResult;
+use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 use std::sync::Once;
 use std::sync::{Arc, Mutex};
@@ -109,6 +110,12 @@ struct JavascriptInterface {
     js_player: JavascriptPlayer,
 }
 
+#[derive(Default, Serialize, Deserialize)]
+pub struct Config {
+    #[serde(default)]
+    letterbox: Letterbox,
+}
+
 /// An opaque handle to a `RuffleInstance` inside the pool.
 ///
 /// This type is exported to JS, and is used to interact with the library.
@@ -124,6 +131,7 @@ impl Ruffle {
         js_player: JavascriptPlayer,
         allow_script_access: bool,
         upgrade_to_https: bool,
+        config: &JsValue,
     ) -> Result<Ruffle, JsValue> {
         if RUFFLE_GLOBAL_PANIC.is_completed() {
             // If an actual panic happened, then we can't trust the state it left us in.
@@ -131,8 +139,17 @@ impl Ruffle {
             return Err("Ruffle is panicking!".into());
         }
         set_panic_handler();
-        Ruffle::new_internal(parent, js_player, allow_script_access, upgrade_to_https)
-            .map_err(|_| "Error creating player".into())
+
+        let config: Config = config.into_serde().unwrap_or_default();
+
+        Ruffle::new_internal(
+            parent,
+            js_player,
+            allow_script_access,
+            upgrade_to_https,
+            config,
+        )
+        .map_err(|_| "Error creating player".into())
     }
 
     /// Stream an arbitrary movie file from (presumably) the Internet.
@@ -298,6 +315,7 @@ impl Ruffle {
         js_player: JavascriptPlayer,
         allow_script_access: bool,
         upgrade_to_https: bool,
+        config: Config,
     ) -> Result<Ruffle, Box<dyn Error>> {
         let _ = console_log::init_with_level(log::Level::Trace);
 
@@ -335,6 +353,7 @@ impl Ruffle {
             log,
             user_interface,
         )?;
+        core.lock().unwrap().set_letterbox(config.letterbox);
 
         // Create instance.
         let instance = RuffleInstance {