TombEngine/Documentation/doc/1 modules/View.html
Lwmte cb23823e64
Video playback (#1625)
* Work

* Work

* Update Video.cpp

* Update Video.cpp

* Update Video.cpp

* Update Video.cpp

* Update Video.cpp

* Working playback

* Update Video.cpp

* Cleanups

* Additions

* Update Video.cpp

* Formatting

* Correct pausing/resuming

* Remove .mov extension, as it's not supported

* Use vector instead of array

* Implement SetIntroVideoPath

* Swap intro image and intro video to better reflect original legal sequence

* Update Gameflow.lua

* Simplify synchronization with VLC thread

* Use Vector2i for sizes, only fetch video dimensions once

* Rename callbacks, move logging callback to a class

* Update Video.cpp

* Update CHANGELOG.md

* Removed empty OnDisplayFrame event

* Rename

* Stop video player if user pressed Alt+F4

* Allow background video playback

* Update Video.cpp

* Update Video.cpp

* Fixed init errors

* Restore .mov default extension for video playback

* Update RendererDraw2D.cpp

* Add video streaming for rectangular faces of room geometry

* Remove magic and use normalized UVs instead

* Use VIDEO_SPRITE_ID instead of NO_VALUE

* Added more scripting API functions for video playback

* Correct variable names

* Shorten notification

* Add GetVideoDominantColor

* Do proper cleanup when alt+F4ing during video playback

* Change game loop deinit to avoid several issues with cleaning up

* Organise `VideoHandler` class

* Randomize glow angle

* Update comment

* Update Video.cpp

* Update Video.cpp

* Fix issues with frame drops in exclusive mode

* Optimize CPU usage in exclusive mode

---------

Co-authored-by: Sezz <sezzary@outlook.com>
2025-04-20 22:06:07 +03:00

816 lines
22 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>TombEngine 1.8.1 Lua API</title>
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>&nbsp;TombEngine</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>1 Modules</h2>
<ul class="nowrap">
<li> <a href="../1 modules/Effects.html">Effects</a></li>
<li> <a href="../1 modules/Flow.html">Flow</a></li>
<li> <a href="../1 modules/Input.html">Input</a></li>
<li> <a href="../1 modules/Inventory.html">Inventory</a></li>
<li> <a href="../1 modules/Logic.html">Logic</a></li>
<li> <a href="../1 modules/Objects.html">Objects</a></li>
<li> <a href="../1 modules/Sound.html">Sound</a></li>
<li> <a href="../1 modules/Strings.html">Strings</a></li>
<li> <a href="../1 modules/Util.html">Util</a></li>
<li> <here>View</here></li>
</ul>
<h2>2 Classes</h2>
<ul class="nowrap">
<li> <a href="../2 classes/Collision.Probe.html">Collision.Probe</a></li>
<li> <a href="../2 classes/Flow.Level.html">Flow.Level</a></li>
<li> <a href="../2 classes/Flow.Settings.html">Flow.Settings</a></li>
<li> <a href="../2 classes/Flow.Statistics.html">Flow.Statistics</a></li>
<li> <a href="../2 classes/Objects.AIObject.html">Objects.AIObject</a></li>
<li> <a href="../2 classes/Objects.Camera.html">Objects.Camera</a></li>
<li> <a href="../2 classes/Objects.LaraObject.html">Objects.LaraObject</a></li>
<li> <a href="../2 classes/Objects.Moveable.html">Objects.Moveable</a></li>
<li> <a href="../2 classes/Objects.Room.html">Objects.Room</a></li>
<li> <a href="../2 classes/Objects.Sink.html">Objects.Sink</a></li>
<li> <a href="../2 classes/Objects.SoundSource.html">Objects.SoundSource</a></li>
<li> <a href="../2 classes/Objects.Static.html">Objects.Static</a></li>
<li> <a href="../2 classes/Objects.Volume.html">Objects.Volume</a></li>
<li> <a href="../2 classes/Strings.DisplayString.html">Strings.DisplayString</a></li>
<li> <a href="../2 classes/View.DisplaySprite.html">View.DisplaySprite</a></li>
</ul>
<h2>3 Primitive Classes</h2>
<ul class="nowrap">
<li> <a href="../3 primitive classes/Flow.Fog.html">Flow.Fog</a></li>
<li> <a href="../3 primitive classes/Flow.Horizon.html">Flow.Horizon</a></li>
<li> <a href="../3 primitive classes/Flow.InventoryItem.html">Flow.InventoryItem</a></li>
<li> <a href="../3 primitive classes/Flow.LensFlare.html">Flow.LensFlare</a></li>
<li> <a href="../3 primitive classes/Flow.SkyLayer.html">Flow.SkyLayer</a></li>
<li> <a href="../3 primitive classes/Flow.Starfield.html">Flow.Starfield</a></li>
<li> <a href="../3 primitive classes/Color.html">Color</a></li>
<li> <a href="../3 primitive classes/Rotation.html">Rotation</a></li>
<li> <a href="../3 primitive classes/Time.html">Time</a></li>
<li> <a href="../3 primitive classes/Vec2.html">Vec2</a></li>
<li> <a href="../3 primitive classes/Vec3.html">Vec3</a></li>
</ul>
<h2>4 Enums</h2>
<ul class="nowrap">
<li> <a href="../4 enums/Collision.MaterialType.html">Collision.MaterialType</a></li>
<li> <a href="../4 enums/Effects.BlendID.html">Effects.BlendID</a></li>
<li> <a href="../4 enums/Effects.EffectID.html">Effects.EffectID</a></li>
<li> <a href="../4 enums/Effects.StreamerFeatherMode.html">Effects.StreamerFeatherMode</a></li>
<li> <a href="../4 enums/Effects.ParticleAnimationType.html">Effects.ParticleAnimationType</a></li>
<li> <a href="../4 enums/Flow.ErrorMode.html">Flow.ErrorMode</a></li>
<li> <a href="../4 enums/Flow.FreezeMode.html">Flow.FreezeMode</a></li>
<li> <a href="../4 enums/Flow.GameStatus.html">Flow.GameStatus</a></li>
<li> <a href="../4 enums/Input.ActionID.html">Input.ActionID</a></li>
<li> <a href="../4 enums/Objects.AmmoType.html">Objects.AmmoType</a></li>
<li> <a href="../4 enums/Objects.HandStatus.html">Objects.HandStatus</a></li>
<li> <a href="../4 enums/Objects.WeaponType.html">Objects.WeaponType</a></li>
<li> <a href="../4 enums/Objects.MoveableStatus.html">Objects.MoveableStatus</a></li>
<li> <a href="../4 enums/Objects.ObjID.html">Objects.ObjID</a></li>
<li> <a href="../4 enums/Objects.RoomFlagID.html">Objects.RoomFlagID</a></li>
<li> <a href="../4 enums/Objects.RoomReverb.html">Objects.RoomReverb</a></li>
<li> <a href="../4 enums/Sound.SoundTrackType.html">Sound.SoundTrackType</a></li>
<li> <a href="../4 enums/Strings.DisplayStringOption.html">Strings.DisplayStringOption</a></li>
<li> <a href="../4 enums/Util.LogLevel.html">Util.LogLevel</a></li>
<li> <a href="../4 enums/View.AlignMode.html">View.AlignMode</a></li>
<li> <a href="../4 enums/View.CameraType.html">View.CameraType</a></li>
<li> <a href="../4 enums/View.PostProcessMode.html">View.PostProcessMode</a></li>
<li> <a href="../4 enums/View.ScaleMode.html">View.ScaleMode</a></li>
</ul>
<h2>5 Lua utility modules</h2>
<ul class="nowrap">
<li> <a href="../5 lua utility modules/CustomBar.html">CustomBar</a></li>
<li> <a href="../5 lua utility modules/Diary.html">Diary</a></li>
<li> <a href="../5 lua utility modules/EventSequence.html">EventSequence</a></li>
<li> <a href="../5 lua utility modules/Timer.html">Timer</a></li>
<li> <a href="../5 lua utility modules/Type.html">Type</a></li>
</ul>
</div>
<div id="content">
<h1>Table <code>View</code></h1>
<p>Functions to manage camera and game view.</p>
<p>
</p>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" ><a href="#FadeIn">FadeIn(speed)</a></td>
<td class="summary">Do a full-screen fade-in from black.</td>
</tr>
<tr>
<td class="name" ><a href="#FadeOut">FadeOut(speed)</a></td>
<td class="summary">Do a full-screen fade-to-black.</td>
</tr>
<tr>
<td class="name" ><a href="#SetCineBars">SetCineBars(height, speed)</a></td>
<td class="summary">Move black cinematic bars in from the top and bottom of the game window.</td>
</tr>
<tr>
<td class="name" ><a href="#SetFOV">SetFOV(angle)</a></td>
<td class="summary">Set field of view.</td>
</tr>
<tr>
<td class="name" ><a href="#GetFOV">GetFOV()</a></td>
<td class="summary">Get field of view.</td>
</tr>
<tr>
<td class="name" ><a href="#GetCameraType">GetCameraType()</a></td>
<td class="summary">Shows the mode of the game camera.</td>
</tr>
<tr>
<td class="name" ><a href="#GetCameraPosition">GetCameraPosition()</a></td>
<td class="summary">Gets current camera position.</td>
</tr>
<tr>
<td class="name" ><a href="#GetCameraTarget">GetCameraTarget()</a></td>
<td class="summary">Gets current camera target.</td>
</tr>
<tr>
<td class="name" ><a href="#GetCameraRoom">GetCameraRoom()</a></td>
<td class="summary">Gets current room where camera is positioned.</td>
</tr>
<tr>
<td class="name" ><a href="#SetPostProcessMode">SetPostProcessMode(effect)</a></td>
<td class="summary">Sets the post-process effect mode, like negative or monochrome.</td>
</tr>
<tr>
<td class="name" ><a href="#SetPostProcessStrength">SetPostProcessStrength(strength)</a></td>
<td class="summary">Sets the post-process effect strength.</td>
</tr>
<tr>
<td class="name" ><a href="#SetPostProcessTint">SetPostProcessTint(tint)</a></td>
<td class="summary">Sets the post-process tint.</td>
</tr>
<tr>
<td class="name" ><a href="#PlayVideo">PlayVideo(fileName[, background][, silent][, loop])</a></td>
<td class="summary">Play a video file.</td>
</tr>
<tr>
<td class="name" ><a href="#StopVideo">StopVideo()</a></td>
<td class="summary">Stop the currently playing video.</td>
</tr>
<tr>
<td class="name" ><a href="#GetVideoPosition">GetVideoPosition()</a></td>
<td class="summary">Gets the currently playing video position.</td>
</tr>
<tr>
<td class="name" ><a href="#SetVideoPosition">SetVideoPosition(position)</a></td>
<td class="summary">Sets the currently playing video position.</td>
</tr>
<tr>
<td class="name" ><a href="#GetVideoDominantColor">GetVideoDominantColor()</a></td>
<td class="summary">Gets the dominant color for the current video frame.</td>
</tr>
<tr>
<td class="name" ><a href="#IsVideoPlaying">IsVideoPlaying([name])</a></td>
<td class="summary">Checks if video is currently playing.</td>
</tr>
<tr>
<td class="name" ><a href="#PlayFlyby">PlayFlyby(seqID)</a></td>
<td class="summary">Play a flyby sequence.</td>
</tr>
<tr>
<td class="name" ><a href="#GetFlybyPosition">GetFlybyPosition(seqID, progress, [loop])</a></td>
<td class="summary">Get a flyby sequence's position at a specified progress point in percent.</td>
</tr>
<tr>
<td class="name" ><a href="#GetFlybyRotation">GetFlybyRotation(seqID, progress, [loop])</a></td>
<td class="summary">Get a flyby sequence's rotation at a specified progress point in percent.</td>
</tr>
<tr>
<td class="name" ><a href="#ResetObjCamera">ResetObjCamera()</a></td>
<td class="summary">Reset object camera back to Lara and deactivate object camera.</td>
</tr>
<tr>
<td class="name" ><a href="#FlashScreen">FlashScreen(color, speed)</a></td>
<td class="summary">Flash screen.</td>
</tr>
<tr>
<td class="name" ><a href="#GetAspectRatio">GetAspectRatio()</a></td>
<td class="summary">Get the display resolution's aspect ratio.</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
<dl class="function">
<dt>
<a name = "FadeIn"></a>
<strong>FadeIn(speed)</strong>
</dt>
<dd>
Do a full-screen fade-in from black.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">speed</span>
<span class="types"><span class="type">float</span></span>
(default 1.0). Speed in units per second. A value of 1 will make the fade take one second.
</li>
</ul>
</dd>
<dt>
<a name = "FadeOut"></a>
<strong>FadeOut(speed)</strong>
</dt>
<dd>
Do a full-screen fade-to-black. The screen will remain black until a call to FadeIn.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">speed</span>
<span class="types"><span class="type">float</span></span>
(default 1.0). Speed in units per second. A value of 1 will make the fade take one second.
</li>
</ul>
</dd>
<dt>
<a name = "SetCineBars"></a>
<strong>SetCineBars(height, speed)</strong>
</dt>
<dd>
Move black cinematic bars in from the top and bottom of the game window.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">height</span>
<span class="types"><span class="type">float</span></span>
(default 30). Percentage of the screen to be covered
</li>
<li><span class="parameter">speed</span>
<span class="types"><span class="type">float</span></span>
(default 30). Coverage percent per second
</li>
</ul>
</dd>
<dt>
<a name = "SetFOV"></a>
<strong>SetFOV(angle)</strong>
</dt>
<dd>
Set field of view.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">angle</span>
<span class="types"><span class="type">float</span></span>
in degrees (clamped to [10, 170])
</li>
</ul>
</dd>
<dt>
<a name = "GetFOV"></a>
<strong>GetFOV()</strong>
</dt>
<dd>
Get field of view.
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">float</span></span>
current FOV angle in degrees
</ol>
</dd>
<dt>
<a name = "GetCameraType"></a>
<strong>GetCameraType()</strong>
</dt>
<dd>
Shows the mode of the game camera.
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../4 enums/View.CameraType.html#">CameraType</a></span>
value used by the Main Camera.
</ol>
<h3>Usage:</h3>
<ul>
<pre class="example">LevelFuncs.OnLoop = <span class="keyword">function</span>()
<span class="keyword">if</span> (View.GetCameraType() == CameraType.COMBAT) <span class="keyword">then</span>
<span class="comment">--Do your Actions here.
</span> <span class="keyword">end</span>
<span class="keyword">end</span></pre>
</ul>
</dd>
<dt>
<a name = "GetCameraPosition"></a>
<strong>GetCameraPosition()</strong>
</dt>
<dd>
Gets current camera position.
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../3 primitive classes/Vec3.html#">Vec3</a></span>
current camera position
</ol>
</dd>
<dt>
<a name = "GetCameraTarget"></a>
<strong>GetCameraTarget()</strong>
</dt>
<dd>
Gets current camera target.
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../3 primitive classes/Vec3.html#">Vec3</a></span>
current camera target
</ol>
</dd>
<dt>
<a name = "GetCameraRoom"></a>
<strong>GetCameraRoom()</strong>
</dt>
<dd>
Gets current room where camera is positioned.
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../2 classes/Objects.Room.html#">Room</a></span>
current room of the camera
</ol>
</dd>
<dt>
<a name = "SetPostProcessMode"></a>
<strong>SetPostProcessMode(effect)</strong>
</dt>
<dd>
Sets the post-process effect mode, like negative or monochrome.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">effect</span>
<span class="types"><a class="type" href="../4 enums/View.PostProcessMode.html#">PostProcessMode</a></span>
type to set.
</li>
</ul>
</dd>
<dt>
<a name = "SetPostProcessStrength"></a>
<strong>SetPostProcessStrength(strength)</strong>
</dt>
<dd>
Sets the post-process effect strength.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">strength</span>
<span class="types"><span class="type">float</span></span>
(default 1.0). How strong the effect is.
</li>
</ul>
</dd>
<dt>
<a name = "SetPostProcessTint"></a>
<strong>SetPostProcessTint(tint)</strong>
</dt>
<dd>
Sets the post-process tint.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">tint</span>
<span class="types"><a class="type" href="../3 primitive classes/Color.html#">Color</a></span>
value to use.
</li>
</ul>
</dd>
<dt>
<a name = "PlayVideo"></a>
<strong>PlayVideo(fileName[, background][, silent][, loop])</strong>
</dt>
<dd>
Play a video file. File should be placed in the <code>FMV</code> folder.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">fileName</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
Video file name. Can be provided without extension, if type is mp4, mkv or avi.
</li>
<li><span class="parameter">background</span>
<span class="types"><span class="type">bool</span></span>
(default: false). Play video in the background mode.
In such case, video won't play in fullscreen, but must be shown using special animated texture type in Tomb Editor, or using <a href="../2 classes/View.DisplaySprite.html#">View.DisplaySprite</a>.
(<em>optional</em>)
</li>
<li><span class="parameter">silent</span>
<span class="types"><span class="type">bool</span></span>
(default: false). Play video without sound.
(<em>optional</em>)
</li>
<li><span class="parameter">loop</span>
<span class="types"><span class="type">bool</span></span>
(default: false). Play video in a loop.
(<em>optional</em>)
</li>
</ul>
</dd>
<dt>
<a name = "StopVideo"></a>
<strong>StopVideo()</strong>
</dt>
<dd>
Stop the currently playing video. Only possible if video is playing in the background mode.
</dd>
<dt>
<a name = "GetVideoPosition"></a>
<strong>GetVideoPosition()</strong>
</dt>
<dd>
Gets the currently playing video position.
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../3 primitive classes/Time.html#">Time</a></span>
Current video position.
</ol>
</dd>
<dt>
<a name = "SetVideoPosition"></a>
<strong>SetVideoPosition(position)</strong>
</dt>
<dd>
Sets the currently playing video position.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">position</span>
<span class="types"><a class="type" href="../3 primitive classes/Time.html#">Time</a></span>
New video position.
</li>
</ul>
</dd>
<dt>
<a name = "GetVideoDominantColor"></a>
<strong>GetVideoDominantColor()</strong>
</dt>
<dd>
Gets the dominant color for the current video frame. If no video is playing, returns black.
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../3 primitive classes/Color.html#">Color</a></span>
Dominant video color.
</ol>
</dd>
<dt>
<a name = "IsVideoPlaying"></a>
<strong>IsVideoPlaying([name])</strong>
</dt>
<dd>
Checks if video is currently playing.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">name</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
Video file name. If provided, checks if the currently playing video file name is the same as the provided one.
(<em>optional</em>)
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">bool</span></span>
True if video is currently playing.
</ol>
</dd>
<dt>
<a name = "PlayFlyby"></a>
<strong>PlayFlyby(seqID)</strong>
</dt>
<dd>
Play a flyby sequence.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">seqID</span>
<span class="types"><span class="type">int</span></span>
Flyby sequence ID.
</li>
</ul>
</dd>
<dt>
<a name = "GetFlybyPosition"></a>
<strong>GetFlybyPosition(seqID, progress, [loop])</strong>
</dt>
<dd>
Get a flyby sequence's position at a specified progress point in percent.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">seqID</span>
<span class="types"><span class="type">int</span></span>
Flyby sequence ID.
</li>
<li><span class="parameter">progress</span>
<span class="types"><span class="type">float</span></span>
Progress point in percent. Clamped to [0, 100].
</li>
<li><span class="parameter">loop</span>
<span class="types"><span class="type">bool</span></span>
Smooth the position near start and end points, as if the sequence is looped.
<em>Optional.</em>
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../3 primitive classes/Vec3.html#">Vec3</a></span>
Position at the given progress point.
</ol>
</dd>
<dt>
<a name = "GetFlybyRotation"></a>
<strong>GetFlybyRotation(seqID, progress, [loop])</strong>
</dt>
<dd>
Get a flyby sequence's rotation at a specified progress point in percent.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">seqID</span>
<span class="types"><span class="type">int</span></span>
Flyby sequence ID.
</li>
<li><span class="parameter">progress</span>
<span class="types"><span class="type">float</span></span>
Progress point in percent. Clamped to [0, 100].
</li>
<li><span class="parameter">loop</span>
<span class="types"><span class="type">bool</span></span>
Smooth the position near start and end points, as if the sequence is looped.
<em>Optional.</em>
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../3 primitive classes/Rotation.html#">Rotation</a></span>
Rotation at the given progress point.
</ol>
</dd>
<dt>
<a name = "ResetObjCamera"></a>
<strong>ResetObjCamera()</strong>
</dt>
<dd>
Reset object camera back to Lara and deactivate object camera.
</dd>
<dt>
<a name = "FlashScreen"></a>
<strong>FlashScreen(color, speed)</strong>
</dt>
<dd>
Flash screen.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">color</span>
<span class="types"><a class="type" href="../3 primitive classes/Color.html#">Color</a></span>
(default Color(255, 255, 255))
</li>
<li><span class="parameter">speed</span>
<span class="types"><span class="type">float</span></span>
(default 1.0). Speed in units per second. Value of 1 will make flash take one second. Clamped to [0.005, 1.0].
</li>
</ul>
</dd>
<dt>
<a name = "GetAspectRatio"></a>
<strong>GetAspectRatio()</strong>
</dt>
<dd>
Get the display resolution's aspect ratio.
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">float</span></span>
Display resolution's aspect ratio.
</ol>
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>