-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathCONTRIBUTING
153 lines (97 loc) · 7.77 KB
/
CONTRIBUTING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
Contributing to the Toonloop Project
------------------------------------
This file describes some development practices and coding standards for this project. Its syntax follows the rst format.
Copyright (C) 2010 Alexandre Quessy.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Version Number
--------------
It is made of major.minor.micro numbers. Releases with an odd minor version number are in an unstable branch, whose API and command line argument might change. (sometimes a lot) When the minor number is even, it means it's a stable branch, with only new features that don't break old ones, or bug fixes.
The version number is located in configure.ac and must always be one micro number ahead, unless this is a tag. That means that if we have released 0.1.0, the version number in configure.ac must be 0.1.1 until we release 0.1.1, and so forth.
The ChangeLog File
------------------
It is generated by calling the following command:
$ git log --pretty=medium > ChangeLog
Creating a Tarball - The Release Process
----------------------------------------
Make the NEWS file is up-to-date.
Make sure the version number in configure.ac is correct.
Update the ChangeLog file while you are at it.
Commit any pending changes.
$ ./autogen.sh
$ ./configure
$ make
$ make distcheck
Create the tag in git.
Update the version number in configure.ac to the next release to come. Make a new commit.
The NEWS file
-------------
The NEWS file contains all the release notes. We list there the bugs fixed and the new features. We also explain the reason for some changes if needed. For example, for a tag 0.1.3, it should contain the release notes for 0.1.0 to 0.1.3, at least.
The README File
---------------
We use the GNU Autotools, and Automake overwrites the INSTALL file. Therefore, we write the installation instructions in the README file, along with a quick explanation of how to use the software, and what it does.
The Manual Page
---------------
The text of manual page for this software is located in the following file:
man/man-toonloop.txt
We use help2man to generate a man page from this file and from the program's output. The man page is the primary location for any help and documentation about using this software.
The TODO File
-------------
We store a list of things todo there. Tasks that are done are in the doc/DONE file.
It's simpler to keep bugs in tickets, but tasks in a TODO file.
This README.txt file is for developers. The installations instructions are one level higher, in the README file.
List of C++ files in Toonloop 2.x
---------------------------------
Here is a short description of each header file:
* application.h : The main loop is there. Parses the command line options.
* clip.h : Stores a list of images.
* config.h : Generated by the autotools.
* configuration.h : Stores the configuration for the app.
* controller.h: Contains the methods and signals to do everything
* gui.h : The Clutter stage
* image.h : Stores a single image.
* log.h : Logging utility.
* moviesaver.h : Saves a movie using symlinks to the images and mencoder.
* pipeline.h : Where most is done. The GST pipeline, writing images to disk, video capture, etc.
* subprocess.h : Tool to call processes.
* timing.h : Tools to measure time and format dates.
* v4l2util.h : Tools to poll V4L2 video devices.
Historic
--------
Let's talk about the choices made in this complete rewrite of Toonloop. This is now the 3rd rewrite of Toonloop, in a third programming language!
Toonloop version 0.x was written in Processing. It is Java. The GNU/Linux version uses some Gstreamer wrapper for video capture. That is very nice and very easy to write for. I did not like how we had to manage the OpenGL coordinates. OpenGL is needed for fullscreen. Also, it seemed like Python was faster than Processing for that kind of task. The 0.x version is still pretty good for a very little amount of code. It offers the possibility to record frame at 30 FPS! That is almost live video editing! For scalability issues, and since I preferred to program in Python at that time, I switched to Python for version 1.x.
In Python, Toonloop 1.x is relying on the Pygame library for the video capture. Was is most annoying is that Pygame's video capture library is far from complete and the development is slow. Also, Pygame's release process could be improved. The packaging is done faster for Ubuntu than for Debian. I never got to install the 1.9 version on a Mac OS X system. Finally, SDL handles pretty badly the fullscreen mode. After working with Gstreamer for an other project, I decided to use it for the video capture in Toonloop 2.x.
GStreamer offers us many means to capture video. It's currently the best cross-platform video capture library. Vicap might comes second. VLC is pretty good too. I wanted to use OpenGL in order to do nice compositing, like the overlay mode, only possible efficiently with GLSL shaders. C++ is harder than Python and Java, and can lead to errors such as memory leak or segmentation faults, but it is also a lot faster when it's time to load an image's pixels. A lower-level approach gives more control to the developer.
Coding style
------------
Let's now describe a bit the C++ coding style in Toonloop.
* variables should be lowercase words, separated by underscores. Like "egg_spam".
* Class attributes should be lowercase words, separated by underscores, with a trailing underscore. Like "egg_spam_".
* Class names should be camel case. Like "EggSpam".
* File names should be lowercase, and the words should be stuck together. Like "eggspam.cpp" and "eggspam.h".
* The file name should be named after the single class it contents, if possible.
* If a file contains no class, but only functions, they should enclosed be in a namespace.
* Try to comment the methods, attributes and classes you write. Use inline comments, plus the Doxygen-style headers.
* Try to explain what a thing does in how you name it.
* Indent with four spaces. No tabs.
* No need to use curly braces with if, for, do, and while statements if they contain only one line of code. (but indent it)
* Since this is C++, use 0, not NULL.
* Similarly, use true/false, not TRUE/FALSE.
* Declare local variables as close as possible to where they are used, not in the beginning of the method.
Libraries we use
----------------
* Use boost::signals2 to subscribe to events.
* Use boost::filesystem for file-related operations.
* Use Clutter for anything that is related to OpenGL.
* Use the ConcurrentQueue class for asynchronous messaging between threads.
Image number maths
------------------
Figuring out what how the writehead and playhead in Toonloop work might not be easy. One might forget it from time to time. That's why I note it here.
The image numbers are in the range [0, n - 1] for the playhead, since it is not possible to play an image that does not exist. For the writehead, the range is [0, n]. That means that when we add a frame, we add it at the position number that was stored in the writehead, and then increment it. When we delete a frame, we delete the image at writehead minus one, unless the writehead is at zero. This behaviour is similar to the STL iterators.
Images storage
--------------
In versions 0.x and 1.x, the images data was stored in the RAM. In this version, we store the images to disk as 100% JPEG. Anyways, the Linux kernel caches what it reads from the disk. The images still need to be decoded on every rendered frame, but JPEG is an old, lightweight image codec.