cortex: org/capture-video.org comparison

comparison org/capture-video.org @ 275:da4de661c5d9

I changed Capture Video\!

author	Dylan Holmes <ocsenave@gmail.com>
date	Wed, 15 Feb 2012 01:15:15 -0600
parents	ecafe87ffddc
children	301e91a6c2d1

comparison

equal deleted inserted replaced

-:12e6231eae8e
+:da4de661c5d9
 video frames. As a result, the game appears to speed up and slow down
 as the computational demands shift, but the end result is perfectly
 smooth video output at a constant framerate.
-* Game-time vs. User-time vs. Video-time
+* Video recording requires a steady framerate
+** The built-in =Timer= rushes to keep up.
-A standard JME3 application that extends =SimpleApplication= or
+#* Game-time vs. User-time vs. Video-time
-=Application= tries as hard as it can to keep in sync with
-/user-time/.  If a ball is rolling at 1 game-mile per game-hour in the
+Standard JME3 applications use a =Timer= object to manage time
-game, and you wait for one user-hour as measured by the clock on your
+in the simulated world. Because most JME3 applications (e.g. games)
-wall, then the ball should have traveled exactly one game-mile. In
+are supposed to happen \ldquo{}live\rdquo{}, the built-in =Timer=
-order to keep sync with the real world, the game throttles its physics
+requires simulated time to match real time. This means that the
-engine and graphics display.  If the computations involved in running
+application must rush to finish all of its calculations on
-the game are too intense, then the game will first skip frames, then
+schedule: the more complicated the calculations, the more the
-sacrifice physics accuracy.  If there are particuraly demanding
+application is obligated to rush. And if the workload becomes too
-computations, then you may only get 1 fps, and the ball may tunnel
+much to handle on schedule, =Timer= forces the application to cut
-through the floor or obstacles due to inaccurate physics simulation,
+corners: it demands fast, approximate answers instead of careful,
-but after the end of one user-hour, that ball will have traveled one
+accurate ones.  Although this policy sometimes causes physically impossible
-game-mile.
+glitches and choppy framerates, it ensures that the user will never be
+kept waiting while the computer stops to make a complicated
-When we're recording video, we don't care if the game-time syncs with
+calculation.
-user-time, but instead whether the time in the recorded video
-(video-time) syncs with user-time. To continue the analogy, if we
+Now, the built-in =Timer= values speed over accuracy because real-time
-recorded the ball rolling at 1 game-mile per game-hour and watched the
+applications require it. On the other hand, if your goal is to record a
-video later, we would want to see 30 fps video of the ball rolling at
+glitch-free video, you need a =Timer= that will take its time to
-1 video-mile per /user-hour/. It doesn't matter how much user-time it
+ensure that all calculations are accurate, even if they take a long time. In the next section, we
-took to simulate that hour of game-time to make the high-quality
+will create a new kind of =Timer=\mdash{}called =IsoTimer=\mdash{}which
-recording.
+slows down to let the computer finish all its calculations. The result
+is a perfectly steady framerate and a flawless physical simulation.
-* COMMENT Two examples to clarify the point:
-** Recording from a Simple Simulation
+# are supposed to happen \ldquo live \rdquo, this =Timer= requires the
+# application to update in real-time. In order to keep up with the real world, JME applications cannot
-*** Without a Special Timer
+# afford to take too much time on expensive computations. Whenever the
+# workload becomes too much for the computer to handle on schedule,
+# =Timer= forces the computer to cut corners, giving fast, approximate
+# answers instead of careful, accurate ones. Although physical accuracy sometimes
+# suffers as a result, this policy ensures that the user will never be
+# kept waiting while the computer stops to make a complicated
+# calculation.
+#fast answers are more important than accurate ones.
+# A standard JME3 application that extends =SimpleApplication= or
+# =Application= tries as hard as it can to keep in sync with
+# /user-time/.  If a ball is rolling at 1 game-mile per game-hour in the
+# game, and you wait for one user-hour as measured by the clock on your
+# wall, then the ball should have traveled exactly one game-mile. In
+# order to keep sync with the real world, the game throttles its physics
+# engine and graphics display.  If the computations involved in running
+# the game are too intense, then the game will first skip frames, then
+# sacrifice physics accuracy.  If there are particuraly demanding
+# computations, then you may only get 1 fps, and the ball may tunnel
+# through the floor or obstacles due to inaccurate physics simulation,
+# but after the end of one user-hour, that ball will have traveled one
+# game-mile.
+# When we're recording video, we don't care if the game-time syncs with
+# user-time, but instead whether the time in the recorded video
+# (video-time) syncs with user-time. To continue the analogy, if we
+# recorded the ball rolling at 1 game-mile per game-hour and watched the
+# video later, we would want to see 30 fps video of the ball rolling at
+# 1 video-mile per /user-hour/. It doesn't matter how much user-time it
+# took to simulate that hour of game-time to make the high-quality
+# recording.
+** COMMENT Two examples to clarify the point:
+*** Recording from a Simple Simulation
+**** Without a Special Timer
 You have a simulation of a ball rolling on an infinite empty plane at
 one game-mile per game-hour, and a really good computer. Normally,
 JME3 will throttle the physics engine and graphics display to sync the
 game-time with user-time. If it takes one-thousandth of a second
 user-time to simulate one-sixtieth of a second game time and another
 user-seconds, then wait, and so on. For every second of user time that
 passes, one second of game-time passes, and the game will run at 60
 frames per user-second.
-*** With a Special Timer
+**** With a Special Timer
 Then, you change the game's timer so that user-time will be synced to
 video-time. Assume that encoding a single frame takes 0 seconds
 user-time to complete.
 Now, JME3 takes advantage of all available resources. It still takes
 When someone watches the video, they will see 60 frames per
 user-second, and $\frac{1}{60}$ video-seconds will pass each frame. It
 will take exactly one hour user-time (and one hour video-time) for the
 ball in the video to travel one video-mile.
-** Recording from a Complex Simulation
+*** Recording from a Complex Simulation
 *** Without a Special Timer
 You have a simulation of a ball rolling on an infinite empty plane at
 one game-mile per game-hour accompanied by multiple explosions
 involving thousands of nodes, particle effects, and complicated shadow
 will appear to flow two-fifths as fast as user time while the game is
 running. However, just as in example one, when all is said and done we
 will have an hour long video at 60 fps.
-* COMMENT proposed names for the new timer
+** COMMENT proposed names for the new timer
 # METRONOME
 # IsoTimer
 # EvenTimer
 # PulseTimer
 # FixedTimer
 # MetronomeTimer
 # ConstantTimer
 # SteadyTimer
-* =IsoTimer= records time like a metronome
+** =IsoTimer= records time like a metronome
 The easiest way to achieve this special timing is to create a new
 timer that always reports the same framerate to JME3 every time it is
 called.
 If an Application uses this =IsoTimer= instead of the normal one, we
 can be sure that every call to =simpleUpdate=, for example, corresponds
 to exactly $(\frac{1}{fps})$ seconds of game-time.
-* Encoding to Video
+* =VideoRecorder= manages video feeds in JMonkeyEngine.
+** =AbstractVideoRecorder= provides a general framework for managing videos.
 Now that the issue of time is solved, we just need a function that
 writes each frame to a video.  We can put this function somewhere
-where it will be called exactly one per frame.
+where it will be called exactly once per frame.
 The basic functions that a =VideoRecorder= should support are
-recording, starting, stopping, and possibly a final finishing step
+recording, starting, stopping, and possibly a cleanup step
-there it finilizes the recording (such as writing headers for a video
+where it finalizes the recording (e.g. by writing headers for a video
 file).
 An appropiate interface describing this behaviour could look like
 this:
 of setup and teardown.
 =./src/com/aurellem/capture/video/AbstractVideoRecorder.java=
 #+include ../../jmeCapture/src/com/aurellem/capture/video/AbstractVideoRecorder.java src java
+** There are many options for handling video files in Java
 If you want to generate video from Java, a great option is [[http://www.xuggle.com/][Xuggle]]. It
 takes care of everything related to video encoding and decoding and
 runs on Windows, Linux and Mac.  Out of all the video frameworks for
-Java I personally like this one the best.
+Java, I personally like this one the best.
 Here is a =VideoRecorder= that uses [[http://www.xuggle.com/][Xuggle]] to write each frame to a
 video file.
 =./src/com/aurellem/capture/video/XuggleVideoRecorder.java=
 #+include ../../jmeCapture/src/com/aurellem/capture/video/XuggleVideoRecorder.java src java
 With this, we are able to record video!
-However, it can be hard to properly install Xuggle. For those of you
+However, it can be hard to properly install Xuggle. If you would rather not use Xuggle, here is an alternate class that uses
-who would rather not use Xuggle, here is an alternate class that uses
 [[http://www.randelshofer.ch/blog/2008/08/writing-avi-videos-in-pure-java/][Werner Randelshofer's]] excellent pure Java AVI file writer.
 =./src/com/aurellem/capture/video/AVIVideoRecorder.java=
 #+include ../../jmeCapture/src/com/aurellem/capture/video/AVIVideoRecorder.java src java
 =./src/com/aurellem/capture/video/FileVideoRecorder.java=
 #+include ../../jmeCapture/src/com/aurellem/capture/video/FileVideoRecorder.java src java
-* /Really/ Simple Video Recording
-The most common case for recording a video is probably to just capture
+* How to record videos yourself
-whatever is on your screen exactly as you see it.  In this case, this
-method will do.
+** Include this code.
+No matter how complicated your application is, it's easy to add
+support for video output with just a few lines of code.
+#  You can also record from multiple ViewPorts as the above example shows.
+And although you can use =VideoRecorder= to record advanced split-screen videos with multiple views, in the simplest case, you want to capture a single view\mdash{}
+exactly what's on screen. In this case, the following simple =captureVideo=
+method will do the job:
 #+begin_src java
 public static void captureVideo(final Application app,
 				final File file) throws IOException{
 final AbstractVideoRecorder videoRecorder;
 };
 app.enqueue(thunk);
 }
 #+end_src
-This will select the appropiate backend =VideoRecorder= class
+This method selects the appropriate =VideoRecorder= class
-depending on the file name you specify, and insturment your
+for the file type you specify, and instructs your
-application to record video to the file.  You should still set the
+application to record video to the file.
-game's timer to an =IsoTimer= with the desired fps.
+Now that you have a =captureVideo= method, you use it like this:
+- Establish an =Isotimer= and set its framerate :: For example, if
+you want to record video with a framerate of 30 fps, include
+the following line of code somewhere in the initializtion of
+your application:
+#+begin_src java :exports code
+this.setTimer(new IsoTimer(30));
+#+end_src
+- Choose the output file :: If you want to record from the game's
+main =ViewPort= to a file called =/home/r/record.flv=, then
+include the following line of code somewhere before you call =app.start()=;
+#+begin_src java :exports code
+Capture.captureVideo(app, new File("/home/r/record.flv"));
+#+end_src
+** Simple example
 This example will record video from the ocean scene from the
-jMonkeyEngine test suite.
+JMonkeyEngine test suite.
 #+begin_src java
 File video = File.createTempFile("JME-water-video", ".avi");
 captureVideo(app, video);
 app.start();
 System.out.println(video.getCanonicalPath());
 I've added support for this under a class called
 =com.aurellem.capture.Capture=. You can get it [[http://hg.bortreb.com/jmeCapture/][here]].
-* Hello Video!
+** Hello Video! example
 I've taken [[http://code.google.com/p/jmonkeyengine/source/browse/trunk/engine/src/test/jme3test/helloworld/HelloLoop.java][=./jme3/src/test/jme3test/helloworld/HelloLoop.java=]] and
 augmented it with video output as follows:
 =./src/com/aurellem/capture/examples/HelloVideo.java=
 </iframe>
 #+END_HTML
-* Summary
+* COMMENT More Examples
-It's quite easy to augment your own application to record video,
-almost regardless of how complicated the actual application is.  You
-can also record from multiple ViewPorts as the above example shows.
-The process for adding video recording to your application is as
-follows:
-Assuming you want to record at 30 fps, add:
-#+begin_src java :exports code
-this.setTimer(new IsoTimer(30));
-#+end_src
-Somewhere in the initialization of your Application.
-If you want to record from the game's main =ViewPort= to a file called
-=/home/r/record.flv=, then add:
-#+begin_src java :exports code
-Capture.captureVideo(app, new File("/home/r/record.flv"));
-#+end_src
-Before you call =app.start()=;
-* More Examples
 ** COMMENT Hello Physics
 =HelloVideo= is boring. Let's add some video capturing to =HelloPhysics=
 and create something fun!
 This example is a modified version of =HelloPhysics= that creates four
 together later.
 JME3 Xuggle Aurellem video capture
-* Sample Videos
+* Showcase of recorded videos
 I encoded most of the original JME3 Hello demos for your viewing
 pleasure, all using the =Capture= and =IsoTimer= classes.
 ** HelloTerrain
 [[http://youtu.be/5_4wyDFwrVQ][HelloTerrain.avi]]

Mercurial > cortex

comparison org/capture-video.org @ 275:da4de661c5d9