obs-studio/README

What is OBS?

  This project is a rewrite of what was formerly known as "Open Broadcaster
  Software", software originally designed for recording and streaming live
  video content, efficiently.


What's the goal of rewriting OBS?

 - Make it multiplatform.  Use multiplatform libraries/functions/classes where
   possible to allow this.  Multi-platform support was one of the primary
   reasons for the rewrite.  This also means using a UI toolkit will be
   necessary for user interface.  It also means allowing the use of OpenGL as
   well as Direct3D.

 - Separate the application from the core, allowing custom application of
   the core if desired, and easier extending of the user interface.

 - Simplify complex systems to not only make it easier to use, but easier to
   maintain.

 - Write a better core API, and design the entire system to be modular.

 - Now that we have much more experience, improve the overall design of all
   the subsystems/API, and minimize/eliminate design flaws.  Make it so we can
   do all the things we've had trouble with before, such as custom outputs,
   multiple outputs at once, better handling of inputs, custom services.

 - Make a better/cleaner code base, use better coding standards, use standard
   libraries where possible (not just STL and C standard library, but also
   things like ffmpeg as well), and improve maintainability of the project as a
   whole.

 - Implement a new API-independent shader/effect system allowing better and
   easier shaders usage and customization without having to duplicate shader
   code.

 - Better device support.  Again, I didn't know what I was getting into when
   I originally started writing code for devices.  It evolved into a totally
   convoluted mess.  I would have improved the existing device plugin code, but
   it was just all so fundamentally bad and flawed that it would have been
   detrimental to progression to continue working on it rather than rewrite it.


What was wrong with the original OBS?

  The original OBS was rewritten not because it was bad, at least in terms of
  optimization.  Optimization and graphics are things I love.  However, there
  were some serious problems with the code and design that were deep and
  fundamental, which prevented myself and other developers from being able to
  improve/extend the application or add new features very easily.

  First, the design flaws:

    - The original OBS was completely and hopelessly hard-coded for windows,
      and only windows.  It was just totally impossible to use it on other
      systems.

    - All the sub-systems were written before I really knew what I was getting
      into.  When I started the project, I didn't really fully comprehend the
      scope of what I would need or how to properly design the project.  My
      design and plans for the application were just to write something that
      would "stream games and a webcam, with things like overlays and such."
      This turned out fine for most casual gamers and streamers (and very
      successful), but left anyone wanting to do anything more advanced left
      massively wanting.

    - Subsystems and core functionalities intermingled in such a way that it
      was a nightmare to get proper custom functionality out of it.  Things
      like QSV had to be meshed in with the main encoding loop, and it just
      made things a nightmare to deal with.  Custom outputs were nigh
      impossible.

    - The API was poorly designed because most of it came after I originally
      wrote the application, it was more of an afterthought, and plugin API
      would routinely break for plugin developers due to changing C++
      interfaces (one of the reasons the core is now C).

    - API was intermeshed with the main executable.  The OBSApi DLL was
      nothing more than basically this mutant growth upon OBS.exe that allowed
      plugin developers to barely write plugins, but all the important API
      code was actually stored in the executable.  Navigation was a total mess.

    - The graphics subsystem, while not bad, was incomplete, and though far
      easier to use than bare D3D, wasn't ideal, and was hard-coded for D3D
      specifically.

    - The devices and audio code was poor, I had no idea what I was getting into
      when I started writing them in.  I did not realize beforehand all the
      device-specific quirks that each device/system could have.  Some devices
      had bad timing and quirks that I never aniticipated while writing them.
      I struggled with devices, and my original design for the audio subsystem
      for example morphed over and over into an abomination that, though works,
      is basically this giant duct-taped zombie monster.

    - Shaders were difficult to customize because they had to be duplicated if
      you wanted slightly different functionality that required more than just
      changing shader constants.

    - Oriantation of sources was fixed, and required special code for each
      source to do any custom modification of rotation/position/scale/etc.
      This is one of those fundamental flaws that I look back on and regret, as
      it was a stupid idea from the beginning.  I originally thought I could
      get more accurate source position/sizes, but it just turned out to be
      totally bad.  Should have been matrices from the beginning just like with
      a regular 3D engine.

  Second, the coding flaws:

    - The coding style was inconsistent.

    - C++98, C-Style C++, there was no exception usage, no STL.  C++ used
      poorly.

    - Not Invented Here Syndrome everywhere.  Custom string functions/classes,
      custom templates, custom everything everywhere.  To be fair, it was all
      hand-me-down code from the early 2000s that I had become used to, but
      that was no excuse -- C-standard libraries and the STL should have been
      used from the beginning over anything else.  That doesn't mean to say
      that using custom stuff is always bad, but doing it to the extent I did
      definitely was.  Made it horrible to maintain as well, required extra
      knowledge for plugin developers and anyone messing with the code.

    - Giant monolithic classes everywhere, the main OBS class was paricularly
      bad in this regard.  This meant navigation was a nightmare, and no one
      really knew where to go or where to add/change things.

    - Giant monolithic functions everywhere.  This was particularly bad
      because it meant that functions became harder to debug and harder to
      keep track of what was going on in any particular function at any given
      time.  These large functions, though not inefficient, were delicate and
      easily breakable.  (See OBS::MainCaptureLoop for a nightmarish example,
      or the listbox subclass window procedure in WindowStuff.cpp)

    - Very large file sizes with everything clumped up into single files (for
      another particularly nightmarish example, see WindowStuff.cpp)

    - Bad formatting.  Code could go beyond 200 columns in some cases, making
      it very unpleasant to read with many editors.  Spaces instead of tabs,
      K&R mixed with allman (which was admittedly my fault).


New (actual) coding guidelines

 - For the C code (especially in the core), guidelines are pretty strict K&R,
   kernel style.  See the linux kernel "CodingStyle" document for more
   information.  That particular coding style guideline is for more than just
   style, it actually helps produce a better overall code base.

 - For C++ code, I still use CamelCase instead of all_lowercase just because
   I prefer it that way, it feels right with C++ for some reason.  It also
   helps make it distinguishable from C code.

 - I've started using 8-column tabs for almost everything -- I really
   personally like it over 4-column tabs.  I feel that 8-column tabs are very
   helpful in preventing large amounts of indentation.  A self-imposed
   limitation, if you will.  I also use actual tabs now, instead of spaces.
   Also, I feel that the K&R style looks much better/cleaner when viewed with
   8-column tabs.

 - Preferred maximum columns: 80.  I've also been doing this because in
   combination with 8-column tabs, it further prevents large/bad functions
   with high indentation.  Another self-imposed limitation.  Also, it makes
   for much cleaner viewing in certain editors that wrap (like vim).