Update REAMEs and doc

This commit is contained in:
brunoherbelin
2025-12-24 08:52:41 +01:00
parent 174f04fbef
commit 7da4f258c9
6 changed files with 245 additions and 237 deletions
+5 -94
View File
@@ -28,9 +28,7 @@ Check the [Quick Installation Guide](https://github.com/brunoherbelin/vimix/wiki
Download and install a released [flatpak package](https://flathub.org/apps/details/io.github.brunoherbelin.Vimix)
flatpak install --user vimix
NB: Build your flatpak package to get the latest beta version; instructions are [here](https://github.com/brunoherbelin/vimix/tree/master/flatpak).
flatpak install vimix
[![vimix](https://snapcraft.io/vimix/badge.svg)](https://snapcraft.io/vimix)
@@ -45,100 +43,13 @@ Install the stable debian package (slower release frequency)
### Mac OSX
Download and open a release package from https://github.com/brunoherbelin/vimix/releases
NB: You'll need to accept the exception in OSX security preference.
#### Download the [latest vimix Release](https://github.com/brunoherbelin/vimix/releases)
# Build vimix
## Clone
To compile vimix from source, read these [instructions in the documentation](https://github.com/brunoherbelin/vimix/tree/master/docs).
git clone --recursive https://github.com/brunoherbelin/vimix.git
For linux, it is simpler to build a flatpak package of the latest beta version. Detailed instructions are [here](https://github.com/brunoherbelin/vimix/tree/master/flatpak);
This will create the directory 'vimix', download the latest version of vimix code,
and (recursively) clone all the internal git dependencies.
## Compile
First time after git clone:
mkdir vimix-build
cd vimix-build
cmake -DCMAKE_BUILD_TYPE=Release ../vimix
cmake --build .
This will create the directory 'vimix-build', configure the program for build, and compile vimix.
If successful, the compilation will have produced the executable `vimix` in the `src` directory.
You can run vimix with `./src/vimix` :
...
[100%] Built target vimix
./src/vimix
## Update clone and re-compile
Run these commands from the `vimix-build` directory if you did 'Clone' and 'Compile' previously and only want to get the latest update and rebuild.
git -C ../vimix/ pull
cmake --build .
This will pull the latest commit from git and recompile.
## Try the Beta branch
Run this commands from the `vimix-build` directory before runing 'Update clone and re-compile above'
git -C ../vimix/ checkout beta
It should say;
branch 'beta' set up to track 'origin/beta'.
Switched to a new branch 'beta'
## Dependencies
**Compiling tools:**
- gcc
- make
- cmake
- git
**Libraries:**
- gstreamer
- gst-plugins (libav, base, good, bad & ugly)
- libglfw3
- libicu (icu-i18n icu-uc icu-io)
Optionnal:
- glm
- stb
- TinyXML2
- AbletonLink
- Shmdata
### Install Dependencies
#### Ubuntu
apt-get install build-essential cmake libpng-dev libglfw3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-libav libicu-dev libgtk-3-dev
Optionnal:
apt-get install libglm-dev libstb-dev libtinyxml2-dev ableton-link-dev
> Follow these instructions to [install Shmdata](https://github.com/nicobou/shmdata/blob/develop/doc/install-from-sources.md).
git clone https://gitlab.com/sat-metalab/shmdata.git
mkdir shmdata-build
cd shmdata-build
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -DCMAKE_BUILD_TYPE=Release -DWITH_PYTHON=0 -DWITH_SDCRASH=0 -DWITH_SDFLOW=0 ../shmdata-build
cmake --build . --target package
sudo dpkg -i ./libshmdata_1.3*_amd64.deb
#### OSX with Brew
brew install cmake libpng glfw gstreamer icu4c
flatpak-builder --user --install --from-git=https://github.com/brunoherbelin/vimix.git --from-git-branch=beta --delete-build-dirs --force-clean build flatpak/io.github.brunoherbelin.Vimix.json
+93
View File
@@ -0,0 +1,93 @@
# Build vimix
## Clone
git clone --recursive https://github.com/brunoherbelin/vimix.git
This will create the directory 'vimix', download the latest version of vimix code,
and (recursively) clone all the internal git dependencies.
## Compile
First time after git clone:
mkdir vimix-build
cd vimix-build
cmake -DCMAKE_BUILD_TYPE=Release ../vimix
cmake --build .
This will create the directory 'vimix-build', configure the program for build, and compile vimix.
If successful, the compilation will have produced the executable `vimix` in the `src` directory.
You can run vimix with `./src/vimix` :
...
[100%] Built target vimix
./src/vimix
## Update clone and re-compile
Run these commands from the `vimix-build` directory if you did 'Clone' and 'Compile' previously and only want to get the latest update and rebuild.
git -C ../vimix/ pull
cmake --build .
This will pull the latest commit from git and recompile.
## Try the Beta branch
Run this commands from the `vimix-build` directory before runing 'Update clone and re-compile above'
git -C ../vimix/ checkout beta
It should say;
branch 'beta' set up to track 'origin/beta'.
Switched to a new branch 'beta'
## Dependencies
**Compiling tools:**
- gcc
- make
- cmake
- git
**Libraries:**
- gstreamer
- gst-plugins (libav, base, good, bad & ugly)
- libglfw3
- libicu (icu-i18n icu-uc icu-io)
Optionnal:
- glm
- stb
- TinyXML2
- AbletonLink
- Shmdata
### Install Dependencies
#### Ubuntu
apt-get install build-essential cmake libpng-dev libglfw3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-libav libicu-dev libgtk-3-dev
Optionnal:
apt-get install libglm-dev libstb-dev libtinyxml2-dev ableton-link-dev
> Follow these instructions to [install Shmdata](https://github.com/nicobou/shmdata/blob/develop/doc/install-from-sources.md).
git clone https://gitlab.com/sat-metalab/shmdata.git
mkdir shmdata-build
cd shmdata-build
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr -DCMAKE_BUILD_TYPE=Release -DWITH_PYTHON=0 -DWITH_SDCRASH=0 -DWITH_SDFLOW=0 ../shmdata-build
cmake --build . --target package
sudo dpkg -i ./libshmdata_1.3*_amd64.deb
#### OSX with Brew
brew install cmake libpng glfw gstreamer icu4c
+6 -13
View File
@@ -13,10 +13,6 @@ The main rendering loop operates at a fixed ~62 FPS framerate with callbacks for
## 1. Main Application Loop
### Location
- **File**: `/home/bh/Claude/VimixDev/vimix/src/main.cpp`
- **Loop**: Lines 261-262
### Loop Structure
```cpp
// Main rendering loop (lines 261-262)
@@ -42,7 +38,6 @@ while ( Rendering::manager().isActive() )
## 2. Main Rendering Loop Implementation
### Location
- **File**: `/home/bh/Claude/VimixDev/vimix/src/RenderingManager.cpp`
- **Method**: `Rendering::draw()` (lines 608-673)
### Rendering Pipeline Flow
@@ -96,7 +91,6 @@ Rendering::draw()
## 3. Scene Update and Rendering (Mixer)
### Location
- **File**: `/home/bh/Claude/VimixDev/vimix/src/Mixer.cpp`
- **Methods**: `Mixer::update()` (lines 86-276), `Mixer::draw()` (lines 278-283)
### Update Phase (`prepare()` callback)
@@ -138,7 +132,7 @@ The actual rendering is delegated to the View's draw method.
### Source Architecture
**Base Class**: `/home/bh/Claude/VimixDev/vimix/src/Source/Source.h`
**Base Class**: `vimix/src/Source/Source.h`
Source hierarchy:
```
@@ -171,7 +165,7 @@ virtual FrameBuffer *frame() const; // Get output texture
### MediaSource (Primary Video Source) Flow
**File**: `/home/bh/Claude/VimixDev/vimix/src/Source/MediaSource.cpp`
**File**: `vimix/src/Source/MediaSource.cpp`
```
MediaSource::update(dt)
@@ -191,7 +185,7 @@ MediaSource::render()
### MediaPlayer Class
**Location**: `/home/bh/Claude/VimixDev/vimix/src/MediaPlayer.h` (Lines 59-434)
**Location**: `/vimix/src/MediaPlayer.h` (Lines 59-434)
Key components:
```cpp
@@ -220,7 +214,7 @@ class MediaPlayer {
### Pipeline Structure
**File**: `/home/bh/Claude/VimixDev/vimix/src/MediaPlayer.cpp`
**File**: `/vimix/src/MediaPlayer.cpp`
```
GStreamer Pipeline:
@@ -298,7 +292,7 @@ static GstFlowReturn callback_new_sample(GstAppSink *sink, gpointer data)
### Session Class
**Location**: `/home/bh/Claude/VimixDev/vimix/src/Session.h`
**Location**: `/vimix/src/Session.h`
```cpp
class Session {
@@ -316,7 +310,7 @@ class Session {
### RenderView (Composition)
**Location**: `/home/bh/Claude/VimixDev/vimix/src/View/RenderView.h`
**Location**: `/vimix/src/View/RenderView.h`
```cpp
class RenderView : public View {
@@ -356,7 +350,6 @@ Result: frame() returns the composed image
## 7. GUI Rendering (ImGui)
### Location
- **File**: `/home/bh/Claude/VimixDev/vimix/src/UserInterfaceManager.cpp`
- **Init**: `UserInterface::Init()` (lines 117-150)
- **Frame Start**: `UserInterface::NewFrame()` (lines 866-871)
- **Render**: `UserInterface::Render()` (lines 1046-1047)
+137
View File
@@ -0,0 +1,137 @@
# Various Notes and reminders
Copyright 2024 Bruno Herbelin
## Publishing new a release
- Update `share/metainfo/io.github.brunoherbelin.Vimix.metainfo.xml`
Add a `<release>`, with date and version number
- Update `snap/snapcraft.yaml`
Change version string
- commit to Beta
- Test the flatpack for Beta
<https://github.com/brunoherbelin/vimix/tree/master/flatpak>
- Test the snap for Beta
```bash
$ snap remove vimix
$ snapcraft pack (from vimix base dir)
$ snap install ./vimix_0.X.Y_amd64.snap --devmode
$ snap connections vimix
```
- Merge Beta into origin/master
- push origin/master
- Create Release & Tag in <https://github.com/brunoherbelin/vimix>
Document new features and major bugfixes
- Edit the Json on <https://github.com/flathub/io.github.brunoherbelin.Vimix>
Set vimix git Tag and Commit #
Merge pull-request after successful flathubbot compilation
(delete branch)
- Follow-up status of flathub package build on <https://buildbot.flathub.org>
(link is sent by email)
## Mac OSX specificities
- Settings are saved in `/Users/[username]/Library/Application Support/vimix`
Instructions to reset in finder, do "Go to folder" (shift+command+G),
enter `/Users/[username]/Library/Application Support/vimix` and delete the folder 'vimix'
- POST INSTALL DMG SIGNING AND NOTARIZATION
1. SIGN DMG
```bash
codesign --force --sign "Developer ID Application: <identityIdentifier>" <pathToDMG>
```
verify with:
```bash
codesign --verify --verbose=2 <pathToDMG>
```
2. SUBMIT TO NOTARIZATION
```bash
xcrun notarytool submit <pathToDMG> --keychain-profile "vimix" --wait
```
verify with:
```bash
xcrun notarytool log xxxx-xxxx-xxx --keychain-profile "vimix"
```
NB: "vimix" is the name of the app-specific password in keychain generated online: <https://support.apple.com/en-us/102654>
3. STAPLE THE TICKET TO THE DISK IMAGE
```bash
xcrun stapler staple <pathToDMG>
```
4. VERIFY NOTARIZATION
```bash
spctl -a -vv -t install <pathToDMG>
```
NB: more info at <https://wiki.lazarus.freepascal.org/Notarization_for_macOS_10.14.5%2B>
## flatpack Development
The flatpak manifest for flathub is at <https://github.com/flathub/io.github.brunoherbelin.Vimix>
To build the vimix flatpak with code from local folder (debugging), change the following:
```json
{
"name": "vimix",
"buildsystem": "cmake",
"config-opts": [
"-DCMAKE_BUILD_TYPE=Release"
],
"sources": [
{
"type":"dir",
"path": "[your_development_dir]/vimix",
}
]
}
```
## Testing performance
Linux perf command
- Allow perf on your system
```bash
sudo sysctl -w kernel.perf_event_paranoid=-1
```
- Launch command to record
```bash
perf record ./vimix
perf record --pid=XXXXX
```
e.g.;
```bash
__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia perf record --call-graph dwarf ./build/src/vimix
```
- Analyse using <https://github.com/KDAB/hotspot>
## Memcheck
To generate memory usage plots in [massif format](https://valgrind.org/docs/manual/ms-manual.html):
```bash
G_SLICE=always-malloc valgrind --tool=massif ./vimix
```
To check for memory leaks:
```bash
G_SLICE=always-malloc valgrind --leak-check=full --log-file=vimix_mem.txt ./vimix
```
-103
View File
@@ -1,103 +0,0 @@
Various Notes and reminders
===========================
Copyright 2024 Bruno Herbelin
Publishing new a release
------------------------
- Update share/metainfo/io.github.brunoherbelin.Vimix.metainfo.xml
Add a <release>, with date and version number
- Update snap/snapcraft.yaml
Change version string
- commit to Beta
- Test the flatpack for Beta
https://github.com/brunoherbelin/vimix/tree/master/flatpak
- Test the snap for Beta
$ snap remove vimix
$ snapcraft pack (from vimix base dir)
$ snap install ./vimix_0.X.Y_amd64.snap --devmode
$ snap connections vimix
- Merge Beta into origin/master
- push origin/master
- Create Release & Tag in https://github.com/brunoherbelin/vimix
Document new features and major bugfixes
- Edit the Json on https://github.com/flathub/io.github.brunoherbelin.Vimix
Set vimix git Tag and Commit #
Merge pull-request after successful flathubbot compilation
(delete branch)
- Follow-up status of flathub package build on https://buildbot.flathub.org
(link is sent by email)
Mac OSX specificities
------------------------
- Settings are saved in /Users/[username]/Library/Application Support/vimix
Instructions to reset in finder, do "Go to folder" (shift+command+G),
enter "/Users/[username]/Library/Application Support/vimix" and delete the folder 'vimix'
- POST INSTALL DMG SIGNING AND NOTARIZATION
1. SIGN DMG
codesign --force --sign "Developer ID Application: <identityIdentifier>" <pathToDMG>
verify with:
codesign --verify --verbose=2 <pathToDMG>
2. SUBMIT TO NOTARIZATION
xcrun notarytool submit <pathToDMG> --keychain-profile "vimix" --wait
verify with:
xcrun notarytool log xxxx-xxxx-xxx --keychain-profile "vimix"
NB: "vimix" is the name of the app-specific password in keychain generated online: https://support.apple.com/en-us/102654
3. STAPLE THE TICKET TO THE DISK IMAGE
xcrun stapler staple <pathToDMG>
4. VERIFY NOTARIZATION
spctl -a -vv -t install <pathToDMG>
NB: more info at https://wiki.lazarus.freepascal.org/Notarization_for_macOS_10.14.5%2B
Testing performance
-------------------
Linux perf command
- Allow perf on your system
sudo sysctl -w kernel.perf_event_paranoid=-1
- Launch command to record
perf record ./vimix
perf record --pid=XXXXX
e.g.;
__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia perf record --call-graph dwarf ./build/src/vimix
- Analyse using https://github.com/KDAB/hotspot
Memcheck
--------
To generate memory usage plots in [massif format](https://valgrind.org/docs/manual/ms-manual.html):
G_SLICE=always-malloc valgrind --tool=massif ./vimix
To check for memory leaks:
G_SLICE=always-malloc valgrind --leak-check=full --log-file=vimix_mem.txt ./vimix
+4 -27
View File
@@ -14,14 +14,12 @@ e.g. for Ubuntu:
If you followed all instructions of the [flatpak setup](https://flatpak.org/setup/), vimix should be in the list of packages.
flatpak install --user vimix
flatpak install vimix
## Build local beta flatpack package of vimix
If you want to have the latest developper version of vimix (before releases), you can build a vimix flatpak yourself.
This way, the application vimix is still sandboxed (i.e. not installing libs in your system), removable (entirely free space after remove) and updatable (just re-compile to update).
If you want to have the latest developper version of vimix (before releases), you can build a vimix flatpak yourself. This way, the application vimix is still sandboxed (i.e. not installing libs in your system), removable (entirely free space after remove) and updatable (just re-compile to update).
### 1. Install flatpak build environments
@@ -35,13 +33,12 @@ Install the runtime environments:
flatpak install org.freedesktop.Sdk/x86_64/25.08
flatpak install org.freedesktop.Platform/x86_64/25.08
### 2. Build vimix flatpak
These settings of git are needed to enable clone of local repos during build (done only once):
git config --global --add protocol.file.allow always
### 2. Build vimix flatpak
Launch the build of the flatpak:
flatpak-builder --user --install --from-git=https://github.com/brunoherbelin/vimix.git --from-git-branch=beta --delete-build-dirs --force-clean build flatpak/io.github.brunoherbelin.Vimix.json
@@ -62,23 +59,3 @@ To run from command line:
flatpak uninstall vimix
# Developper information
The flatpak manifest for flathub is at https://github.com/flathub/io.github.brunoherbelin.Vimix
To build the vimix flatpak with code from local folder (debugging), change the following:
{
"name": "vimix",
"buildsystem": "cmake",
"config-opts": [
"-DCMAKE_BUILD_TYPE=Release"
],
"sources": [
{
"type":"dir",
"path": "[your_development_dir]/vimix",
}
]
}