1 lightweight, vulkan, x11, linux, alsa, audio driven and somewhat
2 self-limiting media pipeline video file player using ffmpeg.
3 "somewhat self-limiting": _without_ lockless and concurrently accessed
6 configure the key bindings and more in "config.h". see
7 make-template.sh: this is a "one compilation unit" project. just
8 compile main.c and link the compiler output file to your ffmpeg libs
9 (we favor the static libs), freetype2 lib (we favor the static lib),
10 your alsa lib (we should make this dynamically loaded). the vulkan
11 loader lib and x11 xcb libs will be dynamically loaded. you have to
12 define the preprocessor macro static as empty or "static". you will
13 probably have to define the _gnu_source macro on most gnu/linux systems.
15 *.c and *.h files, except the fragments *.frag.c *.frag.h, must
16 "successfully" individually compile (cc -c modulo a few warnings).
17 header files are reduced into being forward function declarations, type
18 declarations, and "shared" variables.
20 In your text editor, we would recommend to have displayed the full file
21 paths from the top source dir of the files you are editing, that in
22 order to know where those files are in the component hierarchy, if you
23 are public or local, etc.
25 we introduce naming noise to avoid too much naming collision between
27 - for struct/union types with a "_t" suffix
28 - for "local" variable names, a "_l" suffix
29 - for "public" variable names, a "_p" suffix
30 this allow the project to grow to very large and keep namespace in
31 check without the need of beyond sanity ultra complex compiler naming
32 system. it is a way more reasonable tradeof and is quite less toxic
33 (and in the end it kindof helps to keep track of where things are).
34 we could avoid to use the suffixes ("_l" and "_p") for "long/uniquified
35 identifier" on variables in global scope, but we chose to keep them.
37 we did not use the ffmpeg video scale _filter_, because we did not
38 manage to find without a deep code dive "the ffmpeg right way" to
39 perform ourself the output buffer allocation, which is supposed to be
40 mapped once into gpu accessible mem, then gpu blit-able. we did
41 introduce some names inconsistency with scaler and blit: currently
42 the ffmpeg scaler is only doing pixel format conversion, but the vulkan
43 blit is doing the scaling and the transfer into gpu visible memory.
45 additional important points:
46 - always keep an eye on the content of the ABBREVIATIONS files. don't
47 worry, you'll get used to them quickly.
48 - we did "rewrite" with the preprocessor ffmpeg and alsa identifiers to
49 mostly fit those abbreviations (and as an attempt to tidy a bit their
50 namespace and know where the things are actually going)
51 - to lookup for the real symbols, use the output from the preprocessor,
52 or have a quick look at the header files
53 - to check your namespaces: define an empty STATIC macro and look at
54 the symbols in the output of the compiler, for instance using the
55 "objdump" or "readelf" tools.
56 - we are using our custom vulkan headers.
57 - av*_ (avfilter_, avformat, etc) prefixes are reserved for ffmpeg libs
58 (and the av_* prefix:we don't see it after tidying, but it is still
60 - sws_* prefix is reserved for the ffmpeg video scaling _library_
61 - snd_* prefix is reserved for the alsa lib
62 - vk_* prefix is reserved for the vulkan api
63 - xcb_* prefix is reserved for x11 xcb client lib
64 - all the prefixes from the operating system facilities: epoll_*,
66 - _t suffix is reserved for non primitive types (namespace noise and
68 - _l suffix is reserved for "local" variable names (namespace noise
69 and helps knowing where things are)
70 - _p suffix is reserved for "public" variable names (namespace noise
71 and helps knowing where things are)
73 careful of "standards", here iso c. many times "standards"
74 are, to a certain extend, corporation scams. they want you to depend on
75 their complexity and then will force you to use their implementations
76 because it would be nowhere reasonable to reach the same level of
77 compatibilty with modest development efforts. the best example is being
78 the hard dependence of linux on gcc (clang, over than 1 decade,is a the
79 proof that it would be hard). to approach those, a sane way would be to
80 strip them down to a mimimal usage set. for instance, in iso c, function
81 pointer and object pointer are not the same at all, due to some broken
82 or very old hardware architectures (itanium, 8086 real-mode), but "posix
83 standard" makes those pointers the same.