Improve README/CONTRIBUTING files
Use reStructuredText to allow HTML formatting while still maintaining clarity in the raw text.master
parent
b63e4b055e
commit
41731bb096
64
CONTRIBUTING
64
CONTRIBUTING
|
@ -1,64 +0,0 @@
|
|||
Contributing Information:
|
||||
|
||||
- Our bug tracker is located at (currently linked to forum accounts):
|
||||
https://obsproject.com/mantis/
|
||||
|
||||
- Development forums are currently located at:
|
||||
https://obsproject.com/forum/list/general-development.21/
|
||||
|
||||
- Development IRC channel is primarily #obs-dev on QuakeNet
|
||||
|
||||
- To contribute translations, see:
|
||||
https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
|
||||
|
||||
|
||||
Contributing Guidelines:
|
||||
|
||||
- Code and commits will be reviewed. Reviews will be blunt and honest, and
|
||||
your change probably won't go through the first time, or may be outright
|
||||
rejected. It may require many revisions before changes are finally
|
||||
accepted.
|
||||
|
||||
- If you want to avoid doing a lot of work only to have it rejected, discuss
|
||||
what you want to change it in the main channels/forums/mailing lists before
|
||||
actually working on it. Open source requires thick skin. Please don't be
|
||||
discouraged if your changes don't go through, learn from it and get better.
|
||||
|
||||
- Coding style is Linux-style KNF (kernel normal form). This means K&R, 80
|
||||
columns max, preferable maximum function length of approximately 42 lines, 8
|
||||
character width tabs, lower_case_names, etc. I chose this for the sake of
|
||||
the project. Don't argue about it, just do it. It takes no time to do.
|
||||
|
||||
See https://www.kernel.org/doc/Documentation/CodingStyle for a general
|
||||
guideline (though not necessarily a rulebook, for example we allow the use
|
||||
of boolean return values instead of ints for failure).
|
||||
|
||||
NOTE: C++ is an exception to the lower_case_only rule, CamelCase is
|
||||
encouraged (though not required) to distinguish it from C code. Just a
|
||||
personal and subjective stylistic thing on my part.
|
||||
|
||||
- Commits are not just changes to code; they should also be treated as
|
||||
annotation to code. For that reason, do not put unrelated changes in a
|
||||
single commit. Separate out different changes in to different commits, and
|
||||
make separate pull requests for unrelated changes. Commits should be
|
||||
formatted with the 50/72 standard, and should be descriptive and concise.
|
||||
See http://chris.beams.io/posts/git-commit/ for a summary of how to make
|
||||
good commit messages.
|
||||
|
||||
- Core code is C only (unless there's an operating system specific thing that
|
||||
absolutely requires another language).
|
||||
|
||||
- Modules and UI may use C, C++, or Objective-C (for apple), though please try
|
||||
to use C unless an API you're using requires C++ or Objective-C (such as
|
||||
windows COM classes, or apple Objective-C APIs).
|
||||
|
||||
- If you don't quite know what to work on and just want to help, the bug
|
||||
tracker has a list of things that need to be worked on.
|
||||
|
||||
- Try to respect the wishes of the author(s)/maintainer(s). A good maintainer
|
||||
will always listen, and will often ask others on the project for their
|
||||
opinions, but don't expect things to be completely democratic.
|
||||
|
||||
- Do not use dependencies for the sake of convenience. There's enough
|
||||
dependencies as it is. Use them only if you absolutely have to depend on
|
||||
them.
|
|
@ -0,0 +1,90 @@
|
|||
Contributing
|
||||
============
|
||||
|
||||
Quick Links for Contributing
|
||||
----------------------------
|
||||
|
||||
- Compiling and building OBS Studio:
|
||||
https://github.com/jp9000/obs-studio/wiki/Install-Instructions
|
||||
|
||||
- Our bug tracker (linked to forum accounts):
|
||||
https://obsproject.com/mantis/
|
||||
|
||||
- Development IRC channel: #obs-dev on QuakeNet
|
||||
|
||||
- Development forum:
|
||||
https://obsproject.com/forum/list/general-development.21/
|
||||
|
||||
- To contribute language translations, do not make pull requests.
|
||||
Instead, use crowdin. Read here for more information:
|
||||
https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
|
||||
|
||||
Coding Guidelines
|
||||
-----------------
|
||||
|
||||
- OBS Studio uses kernel normal form (linux variant), for more
|
||||
information, please read here:
|
||||
https://www.kernel.org/doc/Documentation/CodingStyle
|
||||
|
||||
- Avoid trailing spaces. To view trailing spaces before making a
|
||||
commit, use "git diff" on your changes. If colors are enabled for
|
||||
git in the command prompt, it will show you any whitespace issues
|
||||
marked with red.
|
||||
|
||||
- Tabs for indentation, spaces for alignment. Tabs are treated as 8
|
||||
columns wide.
|
||||
|
||||
- 80 columns max
|
||||
|
||||
Commit Guidlines
|
||||
----------------
|
||||
|
||||
- OBS Studio uses the 50/72 standard for commits. 50 characters max
|
||||
for the title (excluding module prefix), an empty line, and then a
|
||||
full description of the commit, wrapped to 72 columns max. See this
|
||||
link for more information: http://chris.beams.io/posts/git-commit/
|
||||
|
||||
- Make sure commit titles are always in present tense, and are not
|
||||
followed by punctuation.
|
||||
|
||||
- Prefix commit titles with the module name, followed by a colon and a
|
||||
space (unless modifying a file in the base directory). When
|
||||
modifying cmake modules, prefix with "cmake". So for example, if you
|
||||
are modifying the obs-ffmpeg plugin::
|
||||
|
||||
obs-ffmpeg: Fix bug with audio output
|
||||
|
||||
Or for libobs::
|
||||
|
||||
libobs: Fix source not displaying
|
||||
|
||||
- If you still need examples, please view the commit history.
|
||||
|
||||
Headers
|
||||
-------
|
||||
|
||||
There's no formal documentation as of yet, so it's recommended to read
|
||||
the headers (which are heavily commented) to learn the API.
|
||||
|
||||
Here are the most important headers to check out::
|
||||
|
||||
libobs/obs.h Main header
|
||||
|
||||
libobs/obs-module.h Main header for plugin modules
|
||||
|
||||
libobs/obs-source.h Creating video/audio sources
|
||||
|
||||
libobs/obs-output.h Creating outputs
|
||||
|
||||
libobs/obs-encoder.h Implementing encoders
|
||||
|
||||
libobs/obs-service.h Implementing custom streaming services
|
||||
|
||||
libobs/graphics/graphics.h Graphics API
|
||||
|
||||
UI/obs-frontend-api/obs-frontend-api.h
|
||||
Front-end API
|
||||
|
||||
If you would like to learn from example, examine the default plugins
|
||||
(in the <plugins> subdirectory). All features of OBS Studio are
|
||||
implemented as plugins.
|
174
README
174
README
|
@ -1,174 +0,0 @@
|
|||
|
||||
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.
|
||||
|
||||
Bug Tracker: https://obsproject.com/mantis/
|
||||
|
||||
We are no longer using GitHub issues! Please use Mantis, and only report
|
||||
bugs and major issues. Do NOT use mantis to ask questions or request
|
||||
features, please keep that to the forums.
|
||||
|
||||
Forum accounts are now linked to Mantis Bug Tracker. To use the bug
|
||||
tracker, simply log in to the forums and then go to the bug tracker link
|
||||
above.
|
||||
|
||||
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 anticipated 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.
|
||||
|
||||
- Orientation 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).
|
|
@ -0,0 +1,44 @@
|
|||
OBS Studio <https://obsproject.com>
|
||||
===================================
|
||||
|
||||
What is OBS Studio?
|
||||
-------------------
|
||||
|
||||
OBS Studio is software designed for capturing, compositing, encoding,
|
||||
recording, and streaming video content, efficiently.
|
||||
|
||||
It's distributed under the GNU General Public License v2 - see the
|
||||
accompanying COPYING file for more details.
|
||||
|
||||
Quick Links
|
||||
-----------
|
||||
|
||||
- Website: https://obsproject.com
|
||||
|
||||
- Help/Guides: https://github.com/jp9000/obs-studio/wiki
|
||||
|
||||
- Forums: https://obsproject.com/forum/
|
||||
|
||||
- Build Instructions: https://github.com/jp9000/obs-studio/wiki/Install-Instructions
|
||||
|
||||
- Bug Tracker: https://obsproject.com/mantis/
|
||||
|
||||
(Note: The bug tracker is linked to forum accounts. To use the bug
|
||||
tracker, log in to a forum account)
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
||||
- If you wish to contribute code to the project, please make sure read
|
||||
the coding and commit guidelines:
|
||||
https://github.com/jp9000/obs-studio/blob/master/CONTRIBUTING.rst
|
||||
|
||||
- If you wish to contribute translations, do not submit pull requests.
|
||||
Instead, please use Crowdin. For more information read this thread:
|
||||
https://obsproject.com/forum/threads/how-to-contribute-translations-for-obs.16327/
|
||||
|
||||
- Other ways to contribute are by helping people out with support on
|
||||
our forums or in our community chat. Please limit support to topics
|
||||
you fully understand -- bad advice is worse than no advice. When it
|
||||
comes to something that you don't fully know or understand, please
|
||||
defer to the official help or official channels.
|
Loading…
Reference in New Issue