change_rate() now works a bit more like expected.

[nageru-docs] / video.rst

diff --git a/video.rst b/video.rst
index e1f1eb54aec8932bf7d2ab26436c3e52ed0cbdca..c41099d6e8aa2db0f4eb38d621acf35dae0c807a 100644 (file)
--- a/video.rst
+++ b/video.rst
@@ -32,15 +32,15 @@ and/or it has an alpha channel you want to use. Getting the format right makes
 for better efficiency; you not only save a conversion step on the CPU, but
 sometimes also on the GPU.
 
 for better efficiency; you not only save a conversion step on the CPU, but
 sometimes also on the GPU.
 

-Videos are loaded like this:
+Videos are loaded like this::

 
   local video = VideoInput.new("filename.mp4", Nageru.VIDEO_FORMAT_YCBCR)
 
 
   local video = VideoInput.new("filename.mp4", Nageru.VIDEO_FORMAT_YCBCR)
 

-or, for a network stream, perhaps:
+or, for a network stream, perhaps::

 
   local video = VideoInput.new("http://localhost/file.nut", Nageru.VIDEO_FORMAT_BGRA)
 
 
   local video = VideoInput.new("http://localhost/file.nut", Nageru.VIDEO_FORMAT_BGRA)
 

-It can then be added to any chain like this:
+It can then be added to any chain like this::

 
   local input = chain:add_video_input(video, false)
 
 
   local input = chain:add_video_input(video, false)
 


@@ -48,7 +48,7 @@ The second parameter specifies no deinterlacing. Note that interlaced video
 is currently not supported, not even with deinterlacing, so this parameter
 must always be false.
 
 is currently not supported, not even with deinterlacing, so this parameter
 must always be false.
 

-You can use the same video object to create many different video inputs:
+You can use the same video object to create many different video inputs::

   
   local input1 = chain1:add_video_input(video, false)
   local input2 = chain2:add_video_input(video, false)
   
   local input1 = chain1:add_video_input(video, false)
   local input2 = chain2:add_video_input(video, false)


@@ -61,11 +61,37 @@ moving the new file atomically into place, you could end up corrupting the file
 Nageru is playing from, causing it to automatically rewind before the end of
 the segment.
 
 Nageru is playing from, causing it to automatically rewind before the end of
 the segment.
 

+Videos are assigned an arbitrary signal number when loaded. Whenever you need
+to refer to this signal number (say, to get its width or height for display),
+you should use *video:get_signal_num()*. Like any other signal, videos have
+a width and height, an interlaced flag (currently always false), a frame rate
+(which can vary during playback) and has_signal/is_connected member functions.
+The former is always true, but the former will be false if the video isn't
+currently playing for whatever reason (e.g., the file is corrupted, or a network
+stream is broken and hasn't reconnected yet).
+

 
 Controlling video playback
 --------------------------
 
 
 Controlling video playback
 --------------------------
 

-TODO
+Themes have some programmatic control over video playback. In particular,
+if you want to make a video start from the beginning, you can do::
+
+  video:rewind()
+
+which will instantly make it start from the first frame again. This can be
+useful if you e.g. want the video to start when you're switching to it,
+or if you're not really using it to loop (e.g. as a transition marker).
+
+You can also change its rate, e.g. by::
+
+  video:change_rate(2.0)
+
+This will make it play at twice its usual speed. Your rate should not be
+negative nor exactly zero. You can set a rate to e.g. 1e-6 if you want to
+in practice stop the video; once you change it back to normal speed,
+the next frame will resume playing.
+

 
 Integration with CasparCG
 -------------------------
 
 Integration with CasparCG
 -------------------------