Add video recording, re-license as GPL v2 (#98)

* Add Record, re-license as GPL v2, FFmpeg is now an optional dependency

* Add video controls

* Add command line and recording to Lua

* Update readme/docs add ffmpeg options

Author: Jerboa-app

.github/workflows/release.yml

@@ -41,13 +41,17 @@ jobs:
 
     - name: install dependencies
       run: |
-        sudo apt-get update && sudo apt-get install -y build-essential xvfb x11-apps imagemagick xorg-dev mesa-common-dev libx11-dev libxrandr-dev libgl1-mesa-dev libglu1-mesa-dev libfreetype6-dev libopenal-dev libsndfile1-dev libudev-dev libxinerama-dev libxcursor-dev xvfb x11-apps vulkan-tools libvulkan-dev vulkan-validationlayers-dev spirv-tools
+        sudo apt-get update && sudo apt-get install -y build-essential xvfb x11-apps imagemagick xorg-dev mesa-common-dev libx11-dev libxrandr-dev libgl1-mesa-dev libglu1-mesa-dev libfreetype6-dev libopenal-dev libsndfile1-dev libudev-dev libxinerama-dev libxcursor-dev xvfb x11-apps vulkan-tools libvulkan-dev vulkan-validationlayers-dev spirv-tools libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
         python3 -m pip install gcovr
     - name: linux-linux
       run: |
-        ./build.sh -t -r -e
+        ./build.sh -r -e --ffmpeg
         mkdir linux-x86_64
+        cp build/sfoav/sfoav linux-x86_64/sfoav-ffmpeg-linux-x86_64
+        mv build/sfoav/sfoav sfoav-ffmpeg
+        ./build.sh -t -r -e
         cp build/sfoav/sfoav linux-x86_64/sfoav-linux-x86_64
+        mv build/sfoav/sfoav sfoav
         cp LICENSE* linux-x86_64/
 
     - name: unit tests with coverage
@@ -91,14 +95,50 @@ jobs:
         export PID=$!
         sleep 10
         xwd -root -silent | convert xwd:- png:screenshot-meshes.png
-        sleep 5 && kill $PID
+        sleep 5 && kill -9 $PID
+        sudo pkill Xvfb
+
+    - name: jo_mpeg video test
+      run: |
+        export DISPLAY=:99
+        sudo Xvfb :99 -screen 0 512x512x24 &
+        sleep 5
+        MESA_GL_VERSION_OVERRIDE=3.3 ./sfoav tests/test_structure_input/HISTORY -script tests/video.lua &
+        export PID=$!
+        sleep 10 && kill -9 $PID
+        sudo pkill Xvfb
+        mkdir jo_mpeg
+        mv *.mp4 jo_mpeg/jo_mpeg.mp4
+
+    - name: ffmpeg video test
+      run: |
+        export DISPLAY=:99
+        sudo Xvfb :99 -screen 0 512x512x24 &
+        MESA_GL_VERSION_OVERRIDE=3.3 ./sfoav-ffmpeg tests/test_structure_input/HISTORY -script tests/video.lua &
+        export PID=$!
+        sleep 10 && kill -9 $PID
+        sudo pkill Xvfb
+        mkdir ffmpeg
+        mv *.mp4 ffmpeg/ffmpeg.mp4
 
     - name: upload screenshots
       uses: actions/upload-artifact@v4
       with:
         name: screenshots
         path: build/screenshot-meshes.png
 
+    - name: upload ffmpeg video
+      uses: actions/upload-artifact@v4
+      with:
+        name: ffmpeg
+        path: ffmpeg/ffmpeg.mp4
+
+    - name: upload jo_mpeg video
+      uses: actions/upload-artifact@v4
+      with:
+        name: jo_mpeg
+        path: jo_mpeg/jo_mpeg.mp4
+
     - name: build artifact
       uses: actions/upload-artifact@v4
       with:
@@ -204,8 +244,9 @@ jobs:
           for release in linux-x86_64 macos windows;
           do
           mkdir $release
-          mv sfoav-$release* $release/
+          mv sfoav*-$release* $release/
           cp LICENSE* $release/
+          cp README.md $release/
           cp SimpleFastOpenAtomicVisualiser.pdf $release
           zip -r $release.zip $release/*
           done

.gitignore

@@ -14,3 +14,4 @@ include/vendored/VulkanSDK/Windows/Include
 include/vendored/VulkanSDK/Windows/lib
 docs/html
 docs/latex
+*.mp4

CMakeLists.txt

@@ -23,6 +23,10 @@ add_compile_definitions(PRODUCT_NAME=${PRODUCT_NAME})
 add_compile_definitions(DESCRIPTION=${DESCRIPTION})
 add_compile_definitions(COPYRIGHT=${COPYRIGHT})
 
+if(FFMPEG)
+    add_compile_definitions(WITH_FFMPEG)
+endif()
+
 list(APPEND CMAKE_CXX_SOURCE_FILE_EXTENSIONS shader)
 
 set(CMAKE_CXX_STANDARD 17)
@@ -127,6 +131,36 @@ target_include_directories(
 	${Vulkan_INCLUDE_DIR}
 )
 
+if (FFMPEG)
+    find_path(AVCODEC_INCLUDE_DIR libavcodec/avcodec.h)
+    find_library(AVCODEC_LIBRARY avcodec)
+
+    find_path(AVFORMAT_INCLUDE_DIR libavformat/avformat.h)
+    find_library(AVFORMAT_LIBRARY avformat)
+
+    find_path(AVUTIL_INCLUDE_DIR libavutil/avutil.h)
+    find_library(AVUTIL_LIBRARY avutil)
+
+    find_path(SWSCALE_INCLUDE_DIR libswscale/swscale.h)
+    find_library(SWSCALE_LIBRARY swscale)
+
+    target_link_libraries(${OUTPUT_NAME}
+        ${AVCODEC_LIBRARY}
+        ${AVFORMAT_LIBRARY}
+        ${AVUTIL_LIBRARY}
+        ${SWSCALE_LIBRARY}
+    )
+
+    target_include_directories(
+        ${OUTPUT_NAME}
+        PUBLIC
+        ${AVCODEC_INCLUDE_DIR}
+        ${AVFORMAT_INCLUDE_DIR}
+        ${AVUTIL_INCLUDE_DIR}
+        ${SWSCALE_INCLUDE_DIR}
+    )
+endif()
+
 if (OSX)
     # https://stackoverflow.com/questions/18391487/compiling-with-glfw3-linker-errors-undefined-reference
     target_link_libraries(${OUTPUT_NAME} "-framework Cocoa -framework IOKit -framework CoreVideo")

DOCUMENTATION.md

@@ -13,7 +13,7 @@
 
 SimpleFastOpenAtomicVisualiser (SFOAV) is intented to enable fast visualisation of atomic and molecular structure files and trajectories.
 
-It is an MIT licensed C++ project hosted here [https://github.com/JerboaBurrow/SimpleFastOpenAtomicVisualiser/](https://github.com/JerboaBurrow/SimpleFastOpenAtomicVisualiser). The visualisations are produced using OpenGL 3.3. There are options for "ray-traced" atoms and bonds or procedural meshes.
+It is a GPL licensed C++ project hosted here [https://github.com/JerboaBurrow/SimpleFastOpenAtomicVisualiser/](https://github.com/JerboaBurrow/SimpleFastOpenAtomicVisualiser). The visualisations are produced using OpenGL 3.3. There are options for "ray-traced" atoms and bonds or procedural meshes.
 
 You can find the latest html Doxygen docs at [https://jerboaburrow.github.io/SimpleFastAtomicVisualiser/](https://jerboaburrow.github.io/SimpleFastAtomicVisualiser/).
 
@@ -83,6 +83,7 @@ Miscellaneous key bindings are:
 | X      | Toggle drawing the coordinate axes | |
 | C      | Toggle drawing the simulation cell | |
 | I      | Toggle information text | |
+| V      | Start or finish a video recording | |
 | ESC    | Quit | |
 
 To enable MSAA at 16x
@@ -99,7 +100,7 @@ sfoav struct.xyz -bondCutOff 1.5
 
 ## Lua scripting
 
-It is possible to write Lua scripts to manipulate visualisation in SFOAV. By supplying a path as ```--script PATH.lua``` to a Lua file, SFOAV will run the file each frame update. The console exports the following methods in the sfoav library.
+It is possible to write Lua scripts to manipulate visualisation in SFOAV. By supplying a path as ```-script PATH.lua``` to a Lua file, SFOAV will run the file each frame update. The console exports the following methods in the sfoav library.
 
 > [!warning]
 > Lua indexes from 1, but all sfoav library functions index from 0.
@@ -114,8 +115,11 @@ It is possible to write Lua scripts to manipulate visualisation in SFOAV. By sup
 | getAtom        | Atom index a | The Atom structure for a |
 | atomCount      | | The number of atoms |
 | getAtomsNeighbours | Atom index x, cutoff distance | The neighbours of a within the cutoff |
-| setText | Text string | The neighbours of a within the cutoff |
+| setText | Text string | Set the text display |
 | getFrame | | The current frame number (from 0) |
+| toggleRecord | | Start or stop video recording |
+| play | | Play the trajectory |
+| pause | | Pause playing the trajectory |
 
 E.g. the following script will set Atom 0 to a random colour every frame.
 
@@ -143,6 +147,20 @@ for i = 1, #neighbours do
 end
 ```
 
+## Video
+
+On macOS and Windows one release exists using jo_mpeg to write mp4 files.
+
+On Linux two releases exist, the standalone ```sfoav``` which uses jo_mpeg for video writing, and the FFmpeg enabled version ```sfoav-ffmpeg``` which requires additional runtime dependencies (FFmpeg). The FFmpeg video quality is generally superior.
+
+Videos are written out with the filename as the current timestamp.
+
+Video frames are recorded at 60 fps whenever the camera or atoms are updated e.g. a new trajectory frame, new colours, camera moved etc.
+
+Frames are written in the background which will impact visualisation frame rate.
+
+For FFmpeg the ```-codec``` option accepts strings as seen via ```ffmpeg -codecs``` e.g. ```-codec nvenc_h264 -qp 21 -preset lossless``` for Nvidia's H264 encoder. Quality may be controlled by ```-preset```, as well as (depending on the codec) the ```-cp```, ```-crf```, and ```-qp``` arguments where 0 is best and 51 is worst. Other FFmpeg options are ```-bitrate``` and ```-maxBFrames``` and ```-gopSize```.
+
 ## Performance
 
 For a system with an intel i7-4790K, Kingston A400 SATA SSD, a GTX 1080 ti, and 16 GB available RAM. SFOAV is capable of rendering at least 5,000,000 static atoms at 60 frames per second with 16x MSAA and with a moveable camera. At this scale moving the atoms will run cause drops to 30 fps, and frame increments will cost ~5 seconds.