npv:_reasonable_ "pedanticage" of the code
[nyanmp.git] / npv / README
blob03fd272bf45480ddbe5aa621de3fc374ff6ff642
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
4         circular buffers.
5 BUILDING:
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.
13 HACKING:
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
25         identifiers:
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
58           around).
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_*,
64           pthread_*, etc.
65         - _t suffix is reserved for non primitive types (namespace noise and
66           clarity)
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)
71 PEDANTIC:
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.