You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+25-23Lines changed: 25 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,13 @@
1
-
# SDL_movie
1
+
# GleedSDL
2
2
3
3
4
4
5
5
This is a simple library for playing **.webm** movies with SDL3. It is intended to be mostly used for playing short cinematics in games, but cautious usage for other purposes is also possible.
6
6
7
7
⚡️ Experimental until said elsewise. 😜
8
8
9
+
Note: library was renamed from SDL_Movie to Gleed to avoid confusion with official SDL satellite libraries.
10
+
9
11
## Features
10
12
11
13
- Provides SDL-like C API
@@ -31,58 +33,58 @@ Note: you will need a C++ compiler to build this library, as `libwebm` parser is
31
33
32
34
## Usage
33
35
34
-
See [basic.cpp](examples/basic.cpp) for a simple example playing Big Buck Bunny short trailer using more low-level `SDL_Movie` object.
36
+
See [basic.cpp](examples/basic.cpp) for a simple example playing Big Buck Bunny short trailer using more low-level `GleedMovie` object.
35
37
36
-
See another [player.cpp](examples/player.cpp) with more high-level `SDL_MoviePlayer` object, which handles all the timing and synchronization for you and is the **recommended way** to use the library, unless you have specific needs.
38
+
See another [player.cpp](examples/player.cpp) with more high-level `GleedMoviePlayer` object, which handles all the timing and synchronization for you and is the **recommended way** to use the library, unless you have specific needs.
37
39
It allows also selecting a movie out of different codec variants.
38
40
39
41
The API is documented in the header file itself: [SDL_movie.h](include/SDL_movie.h).
40
42
41
-
The general workflow for `SDL_Movie` is the following:
43
+
The general workflow for `GleedMovie` is the following:
42
44
43
-
1. Open a .webm file with `SDLMovie_Open(path)` or `SDLMovie_OpenIO(io_stream)`, obtaining a `SDLMovie*` handle.
44
-
2. Optionally, select an audio or video track with `SDLMovie_SelectTrack`. If not called, the first video and audio tracks are selected by default.
45
-
3. In the application loop, call `SDLMovie_DecodeVideoFrame` to decode video frame, and `SDLMovie_DecodeAudioFrame` to decode audio frame.
46
-
4. On success, do useful rendering with video pixels (`SDLMovie_GetVideoFrameSurface`) and audio samples (`SDLMovie_GetAudioSamples`)
47
-
5. Call `SDLMovie_NextVideoFrame` and `SDLMovie_NextAudioFrame` to advance to the next frame. Use `SDLMovie_HasNextVideoFrame` and `SDLMovie_HasNextAudioFrame` to check if there are more frames to decode.
48
-
6. When done, call `SDLMovie_FreeMovie` to free resources.
45
+
1. Open a .webm file with `GleedOpen(path)` or `GleedOpenIO(io_stream)`, obtaining a `GleedMovie*` handle.
46
+
2. Optionally, select an audio or video track with `GleedSelectTrack`. If not called, the first video and audio tracks are selected by default.
47
+
3. In the application loop, call `GleedDecodeVideoFrame` to decode video frame, and `GleedDecodeAudioFrame` to decode audio frame.
48
+
4. On success, do useful rendering with video pixels (`GleedGetVideoFrameSurface`) and audio samples (`GleedGetAudioSamples`)
49
+
5. Call `GleedNextVideoFrame` and `GleedNextAudioFrame` to advance to the next frame. Use `GleedHasNextVideoFrame` and `GleedHasNextAudioFrame` to check if there are more frames to decode.
50
+
6. When done, call `GleedFreeMovie` to free resources.
49
51
50
52
**However**, the main problem with that workflow is that it all timing and synchronization is left to the user. Doing the process above at a frame rate higher than the movie's original will cause inconsistent playback speed and audio desync.
51
53
52
-
Therefore, it's advised to use `SDL_MoviePlayer`. Aside from handling timing for you, it also supports:
54
+
Therefore, it's advised to use `GleedMoviePlayer`. Aside from handling timing for you, it also supports:
53
55
54
56
- Directly feeding audio output to your SDL_AudioDevice.
55
57
- Pausing
56
58
- Disabling audio or video playback, if needed
57
59
- Automatic frame rate adjustment
58
-
- Automatic calculation of time delta (pass `SDL_MOVIE_PLAYER_TIME_DELTA_AUTO` as second argument to `SDLMovie_UpdatePlayer`)
60
+
- Automatic calculation of time delta (pass `GLEED_PLAYER_TIME_DELTA_AUTO` as second argument to `GleedUpdatePlayer`)
59
61
-_Probably will support seeking in future_
60
62
61
63
Very quick example with the player (no error checking):
62
64
63
65
```cpp
64
66
// Initialization
65
67
66
-
SDL_Movie* movie = SDLMovie_Open("bunny.webm");
68
+
GleedMovie* movie = GleedOpen("bunny.webm");
67
69
68
-
SDL_MoviePlayer* player = SDLMovie_CreatePlayer(movie);
70
+
GleedMoviePlayer* player = GleedCreatePlayer(movie);
GleedSetPlayerAudioOutput(player, audio_device); // your SDL_AudioDevice, already opened
75
77
76
78
// Update loop
77
-
SDLMovie_UpdatePlayer(player, SDL_MOVIE_PLAYER_TIME_DELTA_AUTO); //second argument is time delta, you can provide your own
79
+
GleedUpdatePlayer(player, GLEED_PLAYER_TIME_DELTA_AUTO); //second argument is time delta, you can provide your own
78
80
79
81
// Rendering
80
82
SDL_RenderCopy(renderer, video_frame, NULL, NULL); // render video frame
81
83
82
84
// Cleanup
83
-
SDLMovie_FreePlayer(player);
84
-
SDLMovie_FreeMovie(movie, true);
85
-
SDLMovie_DestroyTexture(video_frame);
85
+
GleedFreePlayer(player);
86
+
GleedFreeMovie(movie, true);
87
+
GleedDestroyTexture(video_frame);
86
88
```
87
89
88
90
## Why WebM?
@@ -96,7 +98,7 @@ I have 2 reasons for that:
96
98
1. ffmpeg is _big_ and kinda-overkill when you have control over the input format for your video assets, allowing you to choose one.
97
99
2. I wanted to learn how low-level codecs APIs and struggle a bit :D
98
100
99
-
## How can I convert my video to WebM for SDL_Movie?
101
+
## How can I convert my video to WebM for Gleed?
100
102
101
103
Use `ffmpeg`:
102
104
@@ -122,7 +124,7 @@ For now, it does not support it, only accelerations available are implemented by
122
124
123
125
This library uses quite a lot of dynamic memory allocations, but in general it should not have much impact on memory usage, as most allocations are for one-frame buffers.
124
126
125
-
Although, as an option, you may explicitly call `SDLMovie_PreloadAudioStream` to preload whole audio track into memory for a smoother playback at a cost of longer loading time and higher memory usage.
127
+
Although, as an option, you may explicitly call `GleedPreloadAudioStream` to preload whole audio track into memory for a smoother playback at a cost of longer loading time and higher memory usage.
0 commit comments