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