← Back to branch summary

~medibuntu-maintainers/mplayer/medibuntu.precise

« back to all changes in this revision

Viewing changes to ffmpeg/doc/developer.texi

  • Committer: Gauvain Pocentek
  • Date: 2012-03-06 11:59:12 UTC
  • mfrom: (66.1.15 precise)
  • Revision ID: gauvain@pocentek.net-20120306115912-h9d6kt9j0l532oo5
http://bugs.debian.org/442181
http://bugs.debian.org/481807
http://bugs.debian.org/496106
http://bugs.debian.org/533546
http://bugs.debian.org/568514
http://bugs.debian.org/637077
http://bugs.debian.org/638408
http://bugs.debian.org/643621
http://bugs.debian.org/650339
http://bugs.debian.org/653887
http://bugs.debian.org/654974
* Merge from Ubuntu:
  - put back faac support
  - recommends apport-hooks-medibuntu
  - change Maintainer, Uploaders & Vcs-* fields.
* New upstream snapshot
* upload to unstable
* Build against external libmpeg2
* drop 51_FTBFS_arm.patch again
* no longer build depend on libcdparanoia-dev on the Hurd
* Fix FTBFS on the hurd.
  Thanks to Samuel Thibault <sthibault@debian.org> (Closes: #654974)
* Fix FTBFS on arm
* New upstream snapshot, Closes: #650339, #643621, #481807
* Imported Upstream version 1.0~rc4+svn34492
* Bump standards version
* Bump dependency on libav >= 4:0.8~, Closes: #653887
* Fix build-indep
* Build mplayer-gui again, Closes: #568514
* Drop debian/all-lang-config-mak.sh, no longer needed
* include .dfsg1 in version number
* remove get-orig-source target
* no longer prune compiler flags from the environment
* No longer advertise nor build 3fdx, mga and dxr3 backends,
  Closes: #496106, #442181, #533546
* beautify mplayer version identification string
* Brown paperbag upload.
* Next try to fix build failure on sparce after recent binutils change.
* Brown paperbag upload.
* Really fix build failure on sparc after recent binutils change.
* Properly set Replaces/Conflicts on mplayer2{,-dbg} to avoid
  file overwrite errors.
* Adjust versioning of mplayer listed in the mplayer-dbg's Depends field.
* Fix build failure on sparc after recent binutils change.
* Urgency medium bumped because of RC-level bugfix
  and speeding up x264 transition.
* Update to my @debian.org email.
* Upload to unstable
* Enable joystick support on Linux only, Closes: #638408
* Rebuild fixes toolchain issue on arm, Closes: #637077
* New upstream snapshot
* following the discussion started by Diego Biurrun <diego@biurrun.de>
  in debian-devel, I have prepared a new packaging of 'mplayer'
  (with code that comes from CVS)
* the upstream tar.bz cannot be distributed by Debian, since it contains
   CSS code; so I am repackaging it 
* I have tried my best to address all known issues:
  - the package contains the detailed Copyright made by Diego Biurrun 
  - the package does not contain CSS code, or  AFAIK other code on which 
     there is active patent enforcement
  - there is a script  debian/cvs-changelog.sh  that shows all changes
     done to files included in this source.
    This should comply with GPLv2 sec 2.a  (in spirit if not in letter)
    For this reason, the source code contains CVS directories.
* needs   make (>= 3.80) for 'html-chunked-$(1)' in DOCS/xml/Makefile

* some corrections, as suggested Diego Biurrun
  - binary codecs should go into /usr/lib/codecs (upstream default)
  - better template 'mplayer/install_codecs'
  - an empty 'font=' in mplayer.conf breaks mplayer: postinst corrected
* correction in 'mplayer/cfgnote'
* better mplayer.postinst and mplayer.config

* New upstream release
* better debian/copyright file
* do not ship a skin
* New upstream release
* changed DEB_BUILD_OPTIONS to DEB_BUILD_CONFIGURE ,
  DEB_BUILD_OPTIONS is used as in debian policy
* use gcc-3.4
* changed xlibs-dev to a long list of dependencies, for Debian/etch
* try to adhere to  http://www.mplayerhq.hu/DOCS/tech/binary-packaging.txt
  (see README.Debian for details)
* removed dependency on xlibmesa-dev, disabled opengl
* New upstream release
* Simon McVittie <hacks@pseudorandom.co.uk> wonderful work:
- Work around Debian bug #267442 (glibc's sys/uio.h and gcc's altivec.h have
  conflicting uses for __vector) by re-ordering #includes
- Fix potential symlink attack in ./configure
- Disable support for binary codecs on platforms for which those codecs
  aren't available; also disable the corresponding Debconf note when it's
  inappropriate
- Changed Build-Depends: so it works in pbuilder
- Explicitly build-depend on libjpeg62-dev, libfontconfig1-dev,
  libungif4-dev 
- Tweak debian/rules to avoid certain errors being ignored
- Use --language=all
* provide a target  'debian/rules get-orig-source' 
  that recreates the orig.tar.gz ; then use the above orig.tar.gz
* rewrote some parts of debian/rules
* don't clean and recompile docs if upstream ships them
* mplayer-doc was shipping too much stuff
* translated man pages where not installed properly
* compile with libdv4-dev
* correct README.Debian
* Forgot build-dep on libtheora
* Must not depend on libxvidcore
* New upstream release
* new release.
* rc1 to become 0.90
* new pre-release
* new pre-release
* gtk bug fixed.
* new release.
* version bumped
* 0.60 pre2 release
* 0.60 pre-release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
ffmpeg/doc/developer.texi
17
17
decoding). Look at @file{libavcodec/apiexample.c} to see how to use it.
18
18
 
19
19
@item libavformat is the library containing the file format handling (mux and
20
 
demux code for several formats). Look at @file{ffplay.c} to use it in a
 
20
demux code for several formats). Look at @file{avplay.c} to use it in a
21
21
player. See @file{libavformat/output-example.c} to use it to generate
22
22
audio or video streams.
23
23
 
31
31
 
32
32
You can use Libav in your commercial program, but you must abide to the
33
33
license, LGPL or GPL depending on the specific features used, please refer
34
 
to @url{http://libav.org/legal.html} for a quick checklist and to
35
 
@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv2},
36
 
@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv3},
37
 
@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv2.1},
38
 
@url{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv3} for the
39
 
exact text of the licenses.
 
34
to @uref{http://libav.org/legal.html, our legal page} for a quick checklist and to
 
35
the following links for the exact text of each license:
 
36
@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv2, GPL version 2},
 
37
@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.GPLv3, GPL version 3},
 
38
@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv2.1, LGPL version 2.1},
 
39
@uref{http://git.libav.org/?p=libav.git;a=blob;f=COPYING.LGPLv3, LGPL version 3}.
40
40
Any modification to the source code can be suggested for inclusion.
41
 
The best way to proceed is to send your patches to the Libav mailing list.
 
41
The best way to proceed is to send your patches to the
 
42
@uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
 
43
mailing list.
42
44
 
43
45
@anchor{Coding Rules}
44
46
@section Coding Rules
45
47
 
46
 
Libav is programmed in the ISO C90 language with a few additional
47
 
features from ISO C99, namely:
48
 
@itemize @bullet
49
 
@item
50
 
the @samp{inline} keyword;
51
 
@item
52
 
@samp{//} comments;
53
 
@item
54
 
designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
55
 
@item
56
 
compound literals (@samp{x = (struct s) @{ 17, 23 @};})
57
 
@end itemize
58
 
 
59
 
These features are supported by all compilers we care about, so we will not
60
 
accept patches to remove their use unless they absolutely do not impair
61
 
clarity and performance.
62
 
 
63
 
All code must compile with GCC 2.95 and GCC 3.3. Currently, Libav also
64
 
compiles with several other compilers, such as the Compaq ccc compiler
65
 
or Sun Studio 9, and we would like to keep it that way unless it would
66
 
be exceedingly involved. To ensure compatibility, please do not use any
67
 
additional C99 features or GCC extensions. Especially watch out for:
68
 
@itemize @bullet
69
 
@item
70
 
mixing statements and declarations;
71
 
@item
72
 
@samp{long long} (use @samp{int64_t} instead);
73
 
@item
74
 
@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
75
 
@item
76
 
GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
77
 
@end itemize
78
 
 
 
48
@subsection Code formatting conventions
 
49
The code is written in K&R C style. That means the following:
 
50
@itemize @bullet
 
51
@item
 
52
The control statements are formatted by putting space between the statement
 
53
and parenthesis in the following way:
 
54
@example
 
55
for (i = 0; i < filter->input_count; i++) @{
 
56
@end example
 
57
@item
 
58
The case statement is always located at the same level as the switch itself:
 
59
@example
 
60
switch (link->init_state) @{
 
61
case AVLINK_INIT:
 
62
    continue;
 
63
case AVLINK_STARTINIT:
 
64
    av_log(filter, AV_LOG_INFO, "circular filter chain detected");
 
65
    return 0;
 
66
@end example
 
67
@item
 
68
Braces in function declarations are written on the new line:
 
69
@example
 
70
const char *avfilter_configuration(void)
 
71
@{
 
72
    return LIBAV_CONFIGURATION;
 
73
@}
 
74
@end example
 
75
@item
 
76
In case of a single-statement if, no curly braces are required:
 
77
@example
 
78
if (!pic || !picref)
 
79
    goto fail;
 
80
@end example
 
81
@item
 
82
Do not put spaces immediately inside parentheses. @samp{if (ret)} is
 
83
a valid style; @samp{if ( ret )} is not.
 
84
@end itemize
 
85
 
 
86
There are the following guidelines regarding the indentation in files:
 
87
@itemize @bullet
 
88
@item
79
89
Indent size is 4.
80
 
The presentation is one inspired by 'indent -i4 -kr -nut'.
 
90
@item
81
91
The TAB character is forbidden outside of Makefiles as is any
82
92
form of trailing whitespace. Commits containing either will be
83
93
rejected by the git repository.
 
94
@item
 
95
You should try to limit your code lines to 80 characters; however, do so if
 
96
and only if this improves readability.
 
97
@end itemize
 
98
The presentation is one inspired by 'indent -i4 -kr -nut'.
84
99
 
85
100
The main priority in Libav is simplicity and small code size in order to
86
101
minimize the bug count.
87
102
 
88
 
Comments: Use the JavaDoc/Doxygen
89
 
format (see examples below) so that code documentation
 
103
@subsection Comments
 
104
Use the JavaDoc/Doxygen  format (see examples below) so that code documentation
90
105
can be generated automatically. All nontrivial functions should have a comment
91
106
above them explaining what the function does, even if it is just one sentence.
92
107
All structures and their member variables should be documented, too.
 
108
 
 
109
Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e. replace
 
110
@code{//!} with @code{///} and similar.  Also @@ syntax should be employed
 
111
for markup commands, i.e. use @code{@@param} and not @code{\param}.
 
112
 
93
113
@example
94
114
/**
95
 
 * @@file mpeg.c
 
115
 * @@file
96
116
 * MPEG codec.
97
117
 * @@author ...
98
118
 */
120
140
...
121
141
@end example
122
142
 
 
143
@subsection C language features
 
144
 
 
145
Libav is programmed in the ISO C90 language with a few additional
 
146
features from ISO C99, namely:
 
147
@itemize @bullet
 
148
@item
 
149
the @samp{inline} keyword;
 
150
@item
 
151
@samp{//} comments;
 
152
@item
 
153
designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
 
154
@item
 
155
compound literals (@samp{x = (struct s) @{ 17, 23 @};})
 
156
@end itemize
 
157
 
 
158
These features are supported by all compilers we care about, so we will not
 
159
accept patches to remove their use unless they absolutely do not impair
 
160
clarity and performance.
 
161
 
 
162
All code must compile with recent versions of GCC and a number of other
 
163
currently supported compilers. To ensure compatibility, please do not use
 
164
additional C99 features or GCC extensions. Especially watch out for:
 
165
@itemize @bullet
 
166
@item
 
167
mixing statements and declarations;
 
168
@item
 
169
@samp{long long} (use @samp{int64_t} instead);
 
170
@item
 
171
@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
 
172
@item
 
173
GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
 
174
@end itemize
 
175
 
 
176
@subsection Naming conventions
 
177
All names are using underscores (_), not CamelCase. For example,
 
178
@samp{avfilter_get_video_buffer} is a valid function name and
 
179
@samp{AVFilterGetVideo} is not. The only exception from this are structure
 
180
names; they should always be in the CamelCase
 
181
 
 
182
There are following conventions for naming variables and functions:
 
183
@itemize @bullet
 
184
@item
 
185
For local variables no prefix is required.
 
186
@item
 
187
For variables and functions declared as @code{static} no prefixes are required.
 
188
@item
 
189
For variables and functions used internally by the library, @code{ff_} prefix
 
190
should be used.
 
191
For example, @samp{ff_w64_demuxer}.
 
192
@item
 
193
For variables and functions used internally across multiple libraries, use
 
194
@code{avpriv_}. For example, @samp{avpriv_aac_parse_header}.
 
195
@item
 
196
For exported names, each library has its own prefixes. Just check the existing
 
197
code and name accordingly.
 
198
@end itemize
 
199
 
 
200
@subsection Miscellanous conventions
 
201
@itemize @bullet
 
202
@item
123
203
fprintf and printf are forbidden in libavformat and libavcodec,
124
204
please use av_log() instead.
125
 
 
 
205
@item
126
206
Casts should be used only when necessary. Unneeded parentheses
127
207
should also be avoided if they don't make the code easier to understand.
 
208
@end itemize
 
209
 
 
210
@subsection Editor configuration
 
211
In order to configure Vim to follow Libav formatting conventions, paste
 
212
the following snippet into your @file{.vimrc}:
 
213
@example
 
214
" indentation rules for libav: 4 spaces, no tabs
 
215
set expandtab
 
216
set shiftwidth=4
 
217
set softtabstop=4
 
218
" allow tabs in Makefiles
 
219
autocmd FileType make set noexpandtab shiftwidth=8 softtabstop=8
 
220
" Trailing whitespace and tabs are forbidden, so highlight them.
 
221
highlight ForbiddenWhitespace ctermbg=red guibg=red
 
222
match ForbiddenWhitespace /\s\+$\|\t/
 
223
" Do not highlight spaces at the end of line while typing on that line.
 
224
autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/
 
225
@end example
 
226
 
 
227
For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
228
@example
 
229
(setq c-default-style "k&r")
 
230
(setq-default c-basic-offset 4)
 
231
(setq-default indent-tabs-mode nil)
 
232
(setq-default show-trailing-whitespace t)
 
233
@end example
128
234
 
129
235
@section Development Policy
130
236
 
179
285
   When applying patches that have been discussed (at length) on the mailing
180
286
   list, reference the thread in the log message.
181
287
@item
182
 
    Subscribe to the libav-devel and libav-commits mailing list.
 
288
    Subscribe to the
 
289
    @uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel} and
 
290
    @uref{https://lists.libav.org/mailman/listinfo/libav-commits, libav-commits}
 
291
    mailing lists.
183
292
    Bugs and possible improvements or general questions regarding commits
184
293
    are discussed on libav-devel. We expect you to react if problems with
185
294
    your code are uncovered.
224
333
 
225
334
@section Submitting patches
226
335
 
227
 
First, read the (@pxref{Coding Rules}) above if you did not yet, in particular
 
336
First, read the @ref{Coding Rules} above if you did not yet, in particular
228
337
the rules regarding patch submission.
229
338
 
230
339
As stated already, please do not submit a patch which contains several
238
347
Use the patcheck tool of Libav to check your patch.
239
348
The tool is located in the tools directory.
240
349
 
241
 
Run the @pxref{Regression Tests} before submitting a patch in order to verify
 
350
Run the @ref{Regression Tests} before submitting a patch in order to verify
242
351
it does not cause unexpected problems.
243
352
 
244
353
Patches should be posted as base64 encoded attachments (or any other
245
354
encoding which ensures that the patch will not be trashed during
246
 
transmission) to the libav-devel mailing list, see
247
 
@url{https://lists.libav.org/mailman/listinfo/libav-devel}
 
355
transmission) to the
 
356
@uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
 
357
mailing list.
248
358
 
249
359
It also helps quite a bit if you tell us what the patch does (for example
250
360
'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant
277
387
    AVInputFormat/AVOutputFormat struct?
278
388
@item
279
389
    Did you bump the minor version number (and reset the micro version
280
 
    number) in @file{avcodec.h} or @file{avformat.h}?
 
390
    number) in @file{libavcodec/version.h} or @file{libavformat/version.h}?
281
391
@item
282
392
    Did you register it in @file{allcodecs.c} or @file{allformats.c}?
283
393
@item
310
420
 
311
421
@enumerate
312
422
@item
313
 
    Do the regression tests pass with the patch applied?
 
423
    Does @code{make fate} pass with the patch applied?
314
424
@item
315
425
    Does @code{make checkheaders} pass with the patch applied?
316
426
@item
317
427
    Is the patch against latest Libav git master branch?
318
428
@item
319
 
    Are you subscribed to libav-devel?
320
 
    (@url{https://lists.libav.org/mailman/listinfo/libav-devel}
321
 
     the list is subscribers)
 
429
    Are you subscribed to the
 
430
    @uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
 
431
    mailing list? (Only list subscribers are allowed to post.)
322
432
@item
323
433
    Have you checked that the changes are minimal, so that the same cannot be
324
434
    achieved with a smaller patch and/or simpler final code?
372
482
 
373
483
@section Patch review process
374
484
 
375
 
All patches posted to libav-devel will be reviewed, unless they contain a
 
485
All patches posted to the
 
486
@uref{https://lists.libav.org/mailman/listinfo/libav-devel, libav-devel}
 
487
mailing list will be reviewed, unless they contain a
376
488
clear note that the patch is not for the git master branch.
377
489
Reviews and comments will be posted as replies to the patch on the
378
490
mailing list. The patch submitter then has to take care of every comment,
402
514
to commit the update reference with the change and to explain in the comment
403
515
why the expected result changed.
404
516
 
405
 
Please refer to @file{doc/fate.txt}.
 
517
Please refer to @url{fate.html}.
406
518
 
407
519
@bye