npv/README

   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         (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.
  14 HACKING:
  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.
  19
  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.
  24
  25         we introduce naming noise to avoid too much naming collision between
  26         identifiers:
  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.
  36
  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.
  44
  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
  59           around).
  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_*,
  65           pthread_*, etc.
  66         - _t suffix is reserved for non primitive types (namespace noise and
  67           clarity)
  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)
  72 PEDANTIC:
  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.