NameDateSize

..16-Mar-201612 KiB

.gitignore29-Dec-2012859

AUTHORS29-Dec-2012838

bootstrap29-Dec-2012481

ChangeLog29-Dec-2012568.4 KiB

configure.ac29-Dec-201213.8 KiB

COPYING29-Dec-201269.3 KiB

DCO.developers29-Dec-20121.1 KiB

decoder/29-Dec-20124 KiB

dirac.pc.in29-Dec-2012329

doc/29-Dec-20124 KiB

encoder/29-Dec-20124 KiB

INSTALL29-Dec-20127.7 KiB

libdirac_byteio/29-Dec-20124 KiB

libdirac_common/29-Dec-20124 KiB

libdirac_decoder/29-Dec-20124 KiB

libdirac_encoder/29-Dec-20124 KiB

libdirac_motionest/29-Dec-20124 KiB

m4/29-Dec-20124 KiB

make_debug.sh29-Dec-2012510

Makefile.am29-Dec-20122.2 KiB

NEWS29-Dec-201216.9 KiB

picheader/29-Dec-20124 KiB

README29-Dec-201219.4 KiB

README.developers29-Dec-201213.2 KiB

README.release29-Dec-20123.7 KiB

tests/29-Dec-20124 KiB

TODO29-Dec-2012172

unit_tests/29-Dec-20124 KiB

util/29-Dec-20124 KiB

win/29-Dec-20124 KiB

win32/29-Dec-20124 KiB

README

1README for the Dirac video codec
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4by the BBC R&D Dirac team (diracinfo@rd.bbc.co.uk)
5
6
71. Executive Summary
8~~~~~~~~~~~~~~~~~~~~
9
10Dirac is an open source video codec. It uses a traditional hybrid video codec
11architecture, but with the wavelet transform instead of the usual block
12transforms.  Motion compensation uses overlapped blocks to reduce block
13artefacts that would upset the transform coding stage.
14
15Dirac can code just about any size of video, from streaming up to HD and
16beyond, although certain presets are defined for different applications and
17standards.  These cover the parameters that need to be set for the encoder to
18work, such as block sizes and temporal prediction structures, which must
19otherwise be set by hand.
20
21Dirac is intended to develop into real coding and decoding software, capable
22of plugging into video processing applications and media players that need
23compression. It is intended to develop into a simple set of reliable but
24effective coding tools that work over a wide variety of content and formats,
25using well-understood compression techniques, in a clear and accessible
26software structure. It is not intended as a demonstration or reference coder.
27
28
292. Documentation
30~~~~~~~~~~~~~~~~
31
32Documentation can be found at 
33http://diracvideo.org/wiki/index.php/Main_Page#Documentation
34
353. Building and installing
36~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38  GNU/Linux, Unix, MacOS X, Cygwin, Mingw
39  ---------------------------------------
40    ./configure --enable-debug
41        (to enable extra debug compile options)
42     OR
43    ./configure --enable-profile
44        (to enable the g++ profiling flag -pg)
45     OR
46    ./configure --disable-mmx
47        (to disable MMX optimisation which is enabled by default)
48     OR
49    ./configure --enable-debug --enable-profile
50        (to enable extra debug compile options and profiling options)
51     OR
52     ./configure
53
54     By default, both shared and static libraries are built. To build all-static
55     libraries use
56     ./configure --disable-shared
57
58     To build shared libraries only use
59     ./configure --disable-static
60
61     make
62     make install
63
64  The INSTALL file documents arguments to ./configure such as
65  --prefix=/usr/local (specify the installation location prefix).
66
67  
68  MSYS and Microsoft Visual C++
69  -----------------------------
70     Download and install the no-cost Microsoft Visual C++ 2008 Express
71     Edition  from
72     http://msdn.microsoft.com/vstudio/express/visualc/
73
74     Download and install MSYS (the MinGW Minimal SYStem), MSYS-1.0.10.exe, 
75     from http://www.mingw.org/download.shtml. An MSYS icon will be available
76     on the desktop.
77
78     Click on the MSYS icon on the desktop to open a MSYS shell window.
79
80     Create a .profile file to set up the environment variables required. 
81     vi .profile
82
83     Include the following four lines in the .profile file.
84
85     PATH=/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/Common7/IDE:/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/VC/BIN:/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/Common7/Tools:/c/WINDOWS/Microsoft.NET/Framework/v3.5:/c/WINDOWS/Microsoft.NET/Framework/v2.0.50727:/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/VC/VCPackages:$PATH
86
87     INCLUDE=/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/VC/INCLUDE:$INCLUDE
88     LIB=/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/VC/LIB:$LIB
89
90     LIBPATH=/c/WINDOWS/Microsoft.NET/Framework/v3.5:/c/WINDOWS/Microsoft.NET/Framework/v2.0.50727:/c/Program\ Files/Microsoft\ Visual\ Studio\ 9.0/VC/LIB:$LIBPATH
91
92    (Replace /c/Program\ Files/Microsoft\ Visual\ Studio\ 9/ with
93    the location where VC++ 2008 is installed if necessary)
94
95     Exit from the MSYS shell and click on the MSYS icon on the desktop to open 
96     a new MSYS shell window for the .profile to take effect.
97
98     Change directory to the directory where Dirac was unpacked. By default 
99     only the dynamic libraries are built.
100
101     ./configure CXX=cl LD=cl --enable-debug
102         (to enable extra debug compile options)
103     OR
104     ./configure CXX=cl LD=cl --disable-shared
105         (to build static libraries)
106     OR
107     ./configure CXX=cl LD=cl
108     make
109     make install
110
111     The INSTALL file documents arguments to ./configure such as
112     --prefix=/usr/local (specify the installation location prefix).
113
114  Microsoft Visual C++ .NET 2008
115  ------------------------------
116  Download and install the no-cost Microsoft Visual C++ 2008 Express
117  Edition  from
118  http://www.microsoft.com/express/download/
119
120  The MS VC++ 2008 solution and project files are in win32/VisualStudio 
121  directory.  Double-click on the solution file, dirac.sln, in the 
122  win32/VisualStudio directory.  The target 'Everything' builds the codec 
123  libraries and utilities. Four build-types are supported
124
125  Debug - builds unoptimised encoder and decoder dlls with debug symbols
126  Release - builds optimised encoder and decoder dlls
127  Debug-mmx - builds unoptimised encoder and decoder dlls with debug symbols 
128              and mmx optimisations enabled.
129  Release-mmx - builds optimised encoder and decoder dlls  with mmx 
130              optimisations enabled.
131  Static-Debug - builds unoptimised encoder and decoder static libraries
132                 with debug symbols
133  Static-Release - builds optimised encoder and decoder static libraries
134  Static-Debug-mmx - builds unoptimised encoder and decoder static libraries
135                     with debug symbols and mmx optmisations enabled.
136  Static-Release-mmx - builds optimised encoder and decoder static libraries 
137                       with mmx optmisations enabled.
138 
139  Static libraries are created in the win32/VisualStudio/build/lib/<build-type> directory.
140
141  Encoder and Decoder dlls and import libraries, encoder and decoder apps are 
142  created in the win32/VisualStudio/build/bin/<build-type> directory. The "C" 
143  public API is exported using the _declspec(dllexport) mechanism.
144
145  Conversion utilites are created in the 
146  win32/VisualStudio/build/utils/conversion/<build-type> directory. Only static 
147  versions are  built.  
148  Instrumentation utility is created in the 
149  win32/VisualStudio/build/utils/instrumentation/<build-type> directory. Only 
150  static versions are built.
151
152
153  Older editions of Microsoft Visual C++  (e.g. 2003 and 2005)
154  -----------------------------------------------------------
155
156  NOTE: Since Visual C++ 2008 Express edition is freely available to
157  download, older versions of the Visual C++ editions are no longer
158  supported. So it is suggested that the users upgrade their VC++ environment 
159  to VC++ 2008.
160
1614. Running the example programs
162~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163
1644.1 Command-line parameters
165
166At the moment there is a simple command-line parser class which is 
167used in all the executables. The general procedure for running a program
168is to type:
169
170  prog_name -<flag_name> flag_val ... param1 param2 ...
171
172In other words, options are prefixed by a dash; some options take values, 
173while others are boolean options that enable specific features. For example:
174When running the encoder, the -qf options requires a numeric argument
175specifying the "quality factor" for encoding. The -verbose option enables
176detailed output and does not require an argument.
177
178Running any program without arguments will display a list of parameters and
179options.
180
1814.2 File formats
182
183The example coder and decoder use raw 8-bit planar YUV data.  This means that
184data is stored bytewise, with a frame of Y followed by a frame of U followed
185by a frame of V, all scanned in the usual raster order. The video dimensions
186, frame rate and chroma are passed to the encoder via command line arguments.
187
188Other file formats are supported by means of conversion utilities that
189may be found in the subdirectory util/conversion. These will convert to
190and from raw RGB format, and support all the standard raw YUV formats as
191well as bitmaps. Raw RGB can be obtained as an output from standard conversion
192utilities such as ImageMagick.
193
194Example.
195  Compress an image sequence of 100 frames of 352x288 video in tiff format.
196
197  Step 1.
198
199  Use your favourite conversion routine to produce a single raw RGB file of 
200  all the data. If your routine converts frame-by-frame then you will
201  need to concatenate the output.
202
203  Step 2.
204
205  Convert from RGB to the YUV format of your choice. For example, to do
206  420, type
207
208  RGBtoYUV420 <file.rgb >file.yuv 352 288 100
209
210  Note that this uses stdin and stdout to read and write the data.
211
212  We have provided a script create_test_data.pl to help convert rgb format 
213  files into all the input formats supported by Dirac. The command line
214  arguments it supports can be listed using
215  
216  create_test_data.pl -use
217
218  Sample usage is
219  
220  create_test_data.pl -width=352 -height=288 -num_frames=100 file.rgb
221 
222  (This assumes that the RGBtoYUV utilities  are in a directory specified in
223  PATH variable. If not in the path, then use options -convutildir and to set
224  the directories where the script can find the conversion utilities.)
225
226  The scripts then outputs files in all chroma formats (420, 422,
227  444) supported by Dirac to the current directory.
228
229
230  Step 4.
231
232  Run the encoder. This will produce a locally decoded output in the
233  same format if the locally decoded output is enabled using the -local flag.
234
235  Step 5.
236
237  Convert back to RGB.
238
239  YUV420toRGB <file.yuv >file.rgb 352 288 100
240
241  Step 6.
242
243  Use your favourite conversion utility to convert to the format of your
244  choice.
245
246You can also use the transcode utility to convert data to and from Dirac's
247native formats (see http://zebra.fh-weingarten.de/~transcode/):
248
249  This example uses a 720x576x50 DV source, and transcodes to 720x576 YUV in
250  4:2:0 chroma format.  Cascading codecs (DV + Dirac) is generally a bad idea
251  - use this only if you don't have any other source of uncompressed video.
252
253    transcode -i source.dv -x auto,null --dv_yuy2_mode -k -V -y raw,null -o file.avi
254    tcextract -i test.avi -x rgb > file.yuv
255
256Viewing and playback utilities for uncompressed video include MPlayer and
257ImageMagick's display command.
258
259  Continuing the 352x288 4:2:0 example above, to display a single frame
260  of raw YUV with ImageMagick use the following (use <spacebar> to see
261  subsequent frames):
262
263    display -size 352x288 test.yuv
264
265  Raw YUV 420 data can also be played back in MPlayer - use the following 
266  MPlayer command:
267
268    mplayer -fps 15 -rawvideo on:size=152064:w=352:h=288 test.yuv
269
270  (at the time of writing MPlayer could not playback 4:2:2 or 4:4:4 YUV data)
271
272
2734.3 Encoding
274
275The basic encoding syntax is to type
276
277dirac_encoder [options] file_in file_out
278
279This will compress file_in and produce an output file_out of compressed data.
280
281A locally decoded output file_out.local-dec.yuv and instrumentation data
282file_out.imt  (for debugging the encoder and of interest to developers only)
283are also produced if the -local flag is enabled on the command line.
284
285There are a large number of optional parameters that can be used to run the 
286encoder, all of which are listed below. To encode video you need three types of 
287parameter need to be set:
288
289a) quality factor or target bit rate
290b) source parameters (width, height, frame rate, chroma format)
291c) encoding parameters (motion compensation block sizes, preferred viewing
292   distance)
293
294In practice you don't have to set all these directly because presets can be used
295to use appropriate default values.
296
297a) The most important parameters are the quality factor or target bit rate. 
298
299The quality factor is specified by using the option
300
301qf     : Overall quality factor (>0)
302
303This value is greater than 0, the higher the number, the better
304the quality. Typical high quality is 8-10, but it will vary from sequence to 
305sequence, sometimes higher and sometimes lower.
306
307The target bit rate is set using the option
308
309targetrate : Target bit rate in Kb/s
310
311This will attempt to maintain constant bit rate over the sequence. It works
312reasonably well, but actual bit rate, especially over short sequences, may be
313slightly different from the target. 
314
315Setting -targetrate overrides -qf, in that CBR will still be applied, although
316the initial quality will be set by the given qf value. This might help the CBR
317algorithm to adapt faster.
318
319Setting -lossless overrides both -qf and -targetrate, and enforces lossless 
320coding.
321
322b) Source parameters need to be set as the imput is just a raw YUV file and 
323the encoder doesn't have any information about it.
324
325The best way to set source parameters is to use a preset for
326different video formats. 
327
328The available preset options  are:
329QSIF525   : width=176; height=120; 4:2:0 format; 14.98 frames/sec
330QCIF      : width=176; height=144; 4:2:0 format; 12.5 frames/sec
331SIF525    : width=352; height=240; 4:2:0 format; 14.98 frames/sec
332CIF       : width=352; height=288; 4:2:0 format; 12.5 frames/sec
3334SIF525   : width=704; height=480; 4:2:0 format; 14.98 frames/sec
3344CIF      : width=704; height=576; 4:2:0 format; 12.5  frames/sec
335SD480I60  : width=720; height=480; 4:2:2 format; 29.97 frames/sec
336SD576I50  : width=720; height=576; 4:2:2 format; 25 frames/sec
337HD720P60  : width=1280; height=720; 4:2:2 format; 60 frames/sec
338HD720P50  : width=1280; height=720; 4:2:2 format; 50 frames/sec
339HD1080I60 : width=1920; height=1080; 4:2:2 format; 29,97 frames/sec
340HD1080I50 : width=1920; height=1080; 4:2:2 format; 25 frames/sec
341HD1080P60 : width=1920; height=1080; 4:2:2 format; 59.94 frames/sec
342HD1080P50 : width=1920; height=1080; 4:2:2 format; 50 frames/sec
343DC2K24    : width=2048; height=1080; 4:2:2 format; 24 frames/sec
344DC4K24    : width=4096; height=2160; 4:2:2 format; 24 frames/sec
345UHDTV4K60 : width=3840; height=2160; 4:2:2 format; 59.94 frames/sec
346UHDTV4K50 : width=3840; height=2160; 4:2:2 format; 50 frames/sec
347UHDTV8K60 : width=7680; height=4320; 4:2:2 format; 59.94 frames/sec
348UHDTV8K50 : width=7680; height=4320; 4:2:2 format; 50 frames/sec
349
350The default format used is CUSTOM format which has the following preset values
351width=640; height=480; 4:2:0 format; 23.97 frames/sec.
352
353If your video is not one of these formats, you should pick the nearest preset
354and override the parameters that are different.
355
356Example 1 Simple coding example. Code a 720x576 sequence in Planar 420 format to 
357high quality.
358
359Solution.
360
361  dirac_encoder -cformat YUV420P -SD576I50 -qf 9 test.yuv test_out.drc
362
363Example 2. Code a 720x486 sequence at 29.97 frames/sec in 422 format to 
364medium quality
365
366Solution
367
368  dirac_encoder -SD576I50 -width 720 -height 486 -fr 29.97 -cformat YUV422P -qf 5.5 test.yuv test_out.drc
369
370Source parameters that affect coding are:
371
372width           : Width of video frame
373height          : Height of video frame
374cformat         : Chroma Sampling format. Acceptable values are
375                  YUV444P, YUV422P and YUV420P.
376fr              : Frame rate. Can be a decimal number or a fraction. Examples
377                  of acceptable values are 25, 29.97, 12.5, 30000/1001.
378source_sampling : Source material type - 0 - progressive or 1 - interlaced
379
380For a complete list of source parameters, refer to Annex C of the Dirac 
381Specification.
382
383WARNING!! If you use a preset but don't override source parameters that
384are different, then Dirac will still compress, but the bit rate will be
385much, much higher and there may well be serious artefacts. The encoder prints
386out the parameters it's actually using before starting encoding (in verbose
387mode only), so that you can abort at this point.
388
389c) The presets ALSO set encoding parameters. That's why it's a very good idea
390to use presets, as the encoding parameters are a bit obscure. They're still 
391supported for those who want to experiment, but use with care.
392
393Encoding parameters are:
394
395L1_sep        : the separation between L1 frames (frames that are predicted but 
396                also used as reference frames, like P frames in MPEG-2)
397num_L1        : the number of L1 frames before the next intra frame
398xblen         : the width of blocks used for motion compensation
399yblen         : the height of blocks used for motion compensation
400xbsep         : the horizontal separation between blocks. Always <xblen
401ybsep         : the vertical separation between blocks. Always <yblen
402cpd           : normalised viewing distance parameter, in cycles per degree.
403iwlt_filter   : transform filter to use when encoding INTRA frames, Valid
404                values are DD9_7, LEGALL5_3, DD13_7, HAAR0, HAAR1, FIDELITY,
405                DAUB97. Default value is DD13_7.
406rwlt_filter   : transform filter to use when encoding INTER frames, Valid
407                values are DD9_7, LEGALL5_3, DD13_7, HAAR0, HAAR1, FIDELITY,
408                DAUB97. Default value is DD13_7.
409wlt_depth     : transform depth, i.e number of times the component is split 
410                while applying the wavelet transform
411no_spartition : Do not split a subband into coefficient blocks before 
412                entropy coding
413multi_quants  : If subbands are split into multiple coefficient blocks before
414                entropy coding, assign different quantisers to each block 
415                within the subband.
416prefilter     : Prefilter to apply to input video before encoding. The name of
417                the filter to be used and the filter strength have to be 
418                supplied. Valid filter names are NO_PF, CWM, RECTLP and
419                DIAGLP. Filter strenth range should be in the range 0-10.
420                (note PSNR statistics will be computed relative to the 
421                filtered video if -local is enabled)
422lossless      : Lossless coding.(overrides -qf and -targetrate)
423mv_prec       : Motion vector precision. Valid values are 1 (Pixel precision),
424                1/2 (half-pixel precision), 1/4 (quarter pixel precision which
425                is the default), 1/8 ( Eighth pixel precision).
426full_search   : Use full search motion estimation
427combined_me   : Use combination of all three components to do motion estimation
428field_coding  : Code the input video as fields instead of frames.
429                Default coding is frames.
430use_vlc       : Use VLC for entropy coding of coefficients instead of 
431                arithmetic coding.
432Modifying L1_sep and num_L1 allows for new GOP structures to be used, and
433should be entirely safe. There are two non-GOP modes that can also be used for
434encoding: setting num_L1=0 gives I-frame only coding, and setting L1_sep to
4351 will do IP-only coding (no B-pictures). P-only coding isn't possible, but
436num_L1=very large and L1_sep=1 will approximate it.
437
438Modifying the block parameters is strongly deprecated: it's likely to break
439the encoder as there are many constraints. Modifying cpd will not break
440anything, but will change the way noise is distributed which may be more (or
441less) suitable for your application. Setting cpd equal zero turns off
442perceptual weighting altogether.
443
444For more information, see the algorithm documentation on the website:
445http://diracvideo.org/wiki/index.php/Dirac_Algorithm
446
447Other options. The encoder also supports some other options, which are
448
449verbose   : turn on verbosity (if you don't, you won't see the final bitrate!)
450start     : code from this frame number
451stop      : code up until this frame number
452local     : Generate diagnostics and locally decoded output (to avoid running a
453            decoder to see your video)
454
455Using -start and -stop allows a small section to be coded, rather than the
456whole thing.
457
458If the -local flag is present in the command line, the encoder produces 
459diagnostic information about motion vectors that can be used to debug the 
460encoder algorithm. It also produces a locally decoded picture so that you 
461don't have to run the decoder to see what the pictures are like. 
462
4634.4 Decoding
464
465Decoding is much simpler. Just point the decoder input at the bitstream and the
466output to a file:
467
468  dirac_decoder -verbose test_enc test_dec
469
470will decode test_enc into test_dec with running commentary.
471

README.developers

1Dirac software development practices
2====================================
3
4Contents
5--------
6
71. Licenses and submitting work
8
92. Sourceforge Developers forum
10
113. Mailing lists
12
134. Using the CVS repository
14
155. CVS log messages
16
176. Software practices
18
197. Profiling & optimisation
20
218. Line-endings
22
239. Binary files in CVS
24
25
26
271. Licenses and submitting work
28-------------------------------
29
30Developers submitting work to the Dirac project should print out, 
31complete, and sign the Developer's Certificate of Origin contained 
32in the DCO.developers file. It should be posted to: 
33
34Dr Tim Borer
35BBC Research and Development
36Kingswood Warren
37Tadworth
38Surrey KT20 6NP
39United Kingdom
40
41For simplicity developers must submit code using the same
42license that we distribute under, which is the Mozilla Triple
43license (http://www.mozilla.org/MPL/). Using any other license
44causes complexity and FUD.
45
46Contributions should be in the form of a patch, which may be for a
47whole directory. For changes to an existing file all that is needed
48is to add the author's name to the list of contributors, since the
49license will remain the MPL. For new files, the header in each file
50should be completed from Exhibit A, the Mozilla Triple License (from the
51COPYING file). It should NOT be copied from files already obtained
52in the Dirac project, since some details may differ.
53
54To create a context diff patch run the command
55
56diff -ruN compress-orig compress-mods > patch.txt
57
58   where compress-orig is the directory with the original code and
59   compress-mods is the directory with the modified files.
60
61The patch.txt file should then be submitted to the Sourceforge Patch
62tracker.
63
642. Sourceforge Developers forum
65-------------------------------
66The Developers forum is where Dirac core developers plan and coordinate
67changes to Dirac.  All API changes, new features and implementation
68difficulties are announced and discussed here.
69
70Examples of changes which should be announced in the Developers forum:
71
72  - Pic API change: return bool instead of void for ReadNextFrame
73  - Pic API change: most methods can now throw ErrorState objects
74
75Changes which are small in scope and unlikely to affect developers
76should not be announced on the forum.  Changes which touch
77many files can fall into this category - for example
78
79  - Fixed inconsistent CRLF line-endings to be LF.
80  - Fixed "use of uninitialised variable" cases found by gcc.
81  - Fixed memory leak in all instantiations of Pic (found by valgrind).
82  - Add feature test for stdint.h to be portable to Solaris.
83
84Developers should 'monitor' the forums by going to the forum page and
85clicking 'Monitor this forum'.  Any new message will then be emailed
86to their username@users.sourceforge.net email address.
87  http://sourceforge.net/forum/forum.php?forum_id=353620
88
89
903. Mailing lists
91----------------
92Developers should subscribe to the dirac-announce and dirac-commits
93mailing lists.  dirac-announce is used to announce new releases and
94dirac-commits is sent mail automatically for every commit.
95
96
974. Using the CVS repository
98---------------------------
99
100The latest (but non-stable) version of the code can be downloaded direct
101from the Sourceforge repository using anonymous CVS. Instructions for 
102doing so can be found at the Dirac CVS page: 
103
104http://sourceforge.net/cvs/?group_id=102564 
105
106The Dirac codec module is called 'compress'.
107
108To compile the codec from the CVS sources, the configure script must be
109built using autotools. The required autotool operations have been
110collated in a bootstrap script - simply type 
111
112./bootstrap
113
114at the command prompt in the installation directory. Then follow the
115usual install instructions in the INSTALL document.
116
1175. CVS log messages
118-------------------
119Always indicate why the change is necessary in addition to a succinct summary
120of what as changed.  As the number of developers increases it becomes
121increasingly difficult for developers to understand the changes going on in
122areas they are not familiar with.  If the changes relate to an API change
123developers may not realise this if it is not mentioned in the log message
124as the reason for the change.
125
126E.g.
127  Bad
128  ---
129  - Added gamma parameter
130  - Replace stricmp with strcasecmp
131
132  Good
133  ----
134  - Added gamma parameter to record more accurate data on source material
135  - Enhanced portability: stricmp replaced by strcasecmp (the POSIX standard) 
136
137
1386. Software practices
139---------------------
140I. Portability
141  This project aims to be as portable as possible and to that end follows the
142  following standards:
143    POSIX 1003.1 - System Interfaces volume (XSH) & Threads
144    ISO C99 (1999)
145    ISO C++ (1998)
146  The only exception to this practice is for the Microsoft Visual C++ compiler
147  which continues to fall short of all the above standards.  Where MS VC++
148  is incompatible with the standards, experiment is often necessary to find
149  an alternative usage which works under MS VC++.  Use of the _MSC_VER macro
150  in conditional compilation is the accepted way to accommodate such
151  differences.
152
153II. Coding Style
154
155   The following guidelines must be adhered to while developing code.
156
157-- CVS related tags
158   
159 - Include the following RCS tags in all new files (.cpp and .h). Include them
160   on the first line of the licence block
161
162   Id
163   Name
164
165   E.g.
166   /* ***** BEGIN LICENSE BLOCK *****
167   *
168   * $Id$ $Name$
169   *
170   *  rest of licence text
171   * ***** END LICENSE BLOCK ***** */
172
173
174 - Remove the following tags from all files. Do not include them in new files
175   Author
176   Revision
177   Log
178
179--  General Source code formatting
180
181 - Use spaces in assigment statements and compound statements to make code
182   more readable.
183
184   E.g.
185   a = b;
186   if (a < b)
187   for (i=0; i<10; i++)
188   c = (a < b) ? a : b;
189
190 - Curly braces go on a separate line
191   
192   E.g.
193
194   if (a < b)
195   {
196       statment1;
197       statement2;
198       .
199       .
200       .
201   }
202
203   Curly braces can be ommitted if there is only one statment in the block.
204
205 - Use space between the comment marker and start of text
206   E.g.
207
208   // this is a comment
209   
210   /*
211   * This is a multiple line 
212   * comment
213   */
214
215 - Use spaces instead of tabs for indentation
216
217 - Indent Constructor initialiser lists from the constructor name
218   
219   E.g.
220   MyClass::Myclass (int val) :
221       m_val(val)
222   {
223   }
224
225--  Use of Namespaces
226
227 - All core Dirac functionality must be in the namespace dirac.
228 - All other functionality must be defined in a namespace of its own. E.g.
229   conversion utilities are in the namespace dirac_vu, instrumentation utilities
230   are in the namespace dirac_instr.
231
232--  General naming standards
233
234 - Local variables are lowercase and use underscores to separate words.
235   
236   E.g.
237
238   int outer_loop_idx;
239
240 - Use constants instead of macros
241
242 - Type definitions and Enumerations start with an uppercase letter and
243   use lowercase multi-word names using an uppercase letter for each new word.
244
245   E.g
246
247   typedef int CompressionType;
248   enum CompSort {...};
249
250--  Class Definition
251
252 - Class names start with an uppercase letter and the use lowercase with
253   multi-word names using an uppercase letter for each new word.
254   E.g. ArithCodec
255
256 - Class member variables are lowercase with a leading "m_". Use underscores to
257   separate words.
258
259   E.g.
260   int m_num_contexts;
261
262 - Group declaration of member functions and member variables in the class
263   defintion based on access type.
264
265   E.g
266
267   class MyClass
268   {
269   public:
270       //constructor
271       MyClass (int val);
272       
273       //access functions
274       int Value(void);
275       void SetValue(int val);
276
277   private:
278       void Init(int val);
279
280   private:
281       int m_val;
282   };
283
284 - Avoid declaring public member variables. Make them private and define access
285   functions to set/get their values.
286
287 - Avoid defining functions in class definitions except for trivial functions
288
289 - The declaration syntax for accessor/mutator functions is as follows
290
291   void SetVariable (const VariableType& var);
292   
293   VariableType Variable() const;
294   const VariableType& Variable() const;
295
296
297 - Use builtin copy constructors and assigment operators whenever appropriate
298   e.g. when the class does not use dynamic memory allocation, but their use
299   should be commented. This is to ensure that changes to the class are properly
300   reflected in these operators.
301
302 - Encapsulate enumerated types in the class definition if the enumerated type
303   is relevant only to that class.
304
305 - Nest classes within a class if they have no meaning outside the context of
306   the class.
307
308--  Function Definitions
309
310 - Function names start with an upperccase letter and the use lowercase with
311   multi-word names using an uppercase letter for each new word.
312   E.g. ArithCodec
313
314 - Function parameters are lowercase. Use underscores to separate words.
315
316    void BandCodec::Resize(const int& context_num)
317
318 - Use the following notation for reference parameters in a function
319   void BandCodec::Resize(const int& context_num)
320                  OR
321   void BandCodec::Resize(const int &context_num)
322
323 - Dummy argument names, if used, should be the same in the function
324   declarations and definitions to avoid confusion.
325
326       
327III. Code Review
328
329   All code will be peer-reviewed before being checked in to SourceForge
330   CVS. Developers should use the guidelines specified in the Coding Style
331   sub-section while reviewing code.
332
333IV. Testing with "make check"
334  Developers should aim to have all the regression tests succeed.  If a
335  developer anticipates breaking the tests (while a significant body of work
336  is being undertaken) this must be announced on the Developer Forum, and
337  the fixing of the tests would be coordinated there.
338
339  Only one test file is included in the Dirac distribution. In order to run
340  end to end tests, it is necessary to have test Dirac using all supported
341  sizes and formats. The samples.at test case attempts to handle this by
342  running Dirac encoder/decoder/instrumentation tests on all input files in
343  the directory specified by the env variable DIRAC_INPUT_DATA_DIR.
344
345  Sample files in rgb format are available for download from the Dirac project
346  page on Sourceforge. The main Dirac distribution now includes a scripts
347  create_dirac_testfile.pl that converts an rgb file into all the planar
348  YUV formats supported by Dirac and creates the header files. The -use
349  option to this script display usage information. See Step 3 in section
350  4.2 (File Formats) of the README file for an example of how to use this
351  script.
352  
353
354  Developers should also aim to have good test coverage especially when
355  adding functionality.  When adding a new feature, expect to be asked
356  "Where's the test?"
357
358  A new target 'valgrind-check' has been included which uses valgrind, if 
359  available, to check for memory leaks, uninitialised memory reads, invalid
360  writes etc.
361
362
3637. Profiling & optimisation
364---------------------------
365Dirac is alpha software so developers cannot expect optimisation improvements
366to survive algorithm improvements or code refactoring and restructuring.  That
367being said, the Dirac maintainers would like to encourage profiling analysis
368and portable and modular optimisation.  Developers are encouraged to share
369their profiling analysis techniques and results.  The following guidelines
370should be followed:
371
372  - Any optimisation patch must be accompanied by at least a summary of
373    profile analysis and timing results for a range of video material.  There
374    must be sufficient information for other developers to reproduce the
375    results.
376
377  - The preferred method for introducing MMX/SSE/SSE2 optimisation is C/C++ 
378    intrinsics, since this is well supported by GNU C++, Intel C++ and (more or
379    less) MSVC.  See libdirac_motionest/me_utils_mmx.cpp.
380
381  - Developers should take extra care to check their optimisation produces 
382    indentical bitstream output for the encoder, or identical uncompressed
383    output for the decoder compared to the unoptimised version.
384
385  - x86-specific optimisations need not be limited to MMX since SSE is
386    readily available on PentiumIII and AMD Athlons.  SSE2 optimisation is
387    encouraged since it becoming more commonly available (on Pentium4,
388    Athlon64 and Opteron), but take care to use a portable 16byte memory
389    alignment technique.
390
391  - ./configure detects MMX availability and sets the macro HAVE_MMX, if 
392    MMX optimisations is available, by default. To disable MMX optimisations
393    use the --disable-mmx flag with configure.
394
395Profiling can be supported by adding the following parameter to ./configure
396before building:
397
398--enable-profile
399
400The code can then be profiled by, for example, gprof.
401
402
4038. Line-endings
404---------------
405All source code and documentation will have LF line-endings, include makefiles
406and scripts.  The only exception will be for .vcproj and .sln (and any other
407WIN32 specific) files which will not function under MS VC++ unless they use
408CR-LF line-endings.
409
410
4119. Binary files in CVS
412----------------------
413CVS will modify files during checkin and checkout unless they are tagged as
414binary.  The modifications include translation of CR-LF <-> LF (depending on
415the OS of the CVS client) and expansion of CVS keywords such as $Id and $Log.
416
417Files which must not be modified in this way must be tagged as binary either
418using the add command or admin command:
419  cvs add -kb fig1.jpg
420  cvs admin -kb fig1.jpg  (for files already in CVS)
421
422MS VC++ project files, such as .vcproj and .sln, fall into this category since
423they do not function if their line-endings are not CR-LF.
424

README.release

1Checklist for releasing new versions of Dirac
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31.    Compilation
4
51.1    Compile with gcc under Linux with debug options on and remove all errors
6and warnings (use ./configure --enable-debug)
7
81.2    Compile with icc under Linux with debug options and remove all errors 
9and warnings (use ./configure CXX=icc --enable-debug)
10
111.3    Compile with cl under Windows and MSYS with debug options 
12and remove all errors and warnings (use ./configure --enable-debug)
13
141.4 Compile with VC++ under Windows XP/2000 with debug options and remove all 
15errors and warnings
16
172.    Execution
18
192.1    Run make check with gcc and icc and cl makes.
20
212.2    Check that a) the Linux gcc decoder executable can decode the output of 
22the Windows VC++ encoder executable and the decoder output is the same as the 
23locally decoded encoder output; and b) the Windows VC++ decoder executable can 
24decode the output of the Linux gcc encoder executable and the decoder output 
25is the same as the locally decoded encoder output.
26
272.3    Check that diagnostics tool works
28
293    Inspection
30
313.1    View the test picture results of make check and check that file sizes 
32and picture quality are 'reasonable'.
33
344.    Code
35
36There is no need to inspect the code in detail as this should have been done as 
37part of the review process prior to being placed on the diracvideo Git
38repository.
39
404.1    Run dos2unix on all test files to remove dos line-breaks.
41
424.2    Ensure that all new source files (.cpp, .c and .h) include the Id and
43       Name RCS tags.
44
455.    Documentation
46
475.1 Check that the doxygen API docs build without error. Check that API 
48documents have been generated for any added executables or libraries.
49
505.2 Place the API docs on the website.
51
525.3 Update algorithm documentation if necessary and place on the website.
53
545.4 Produce READMEs for any added utilities or separate programs.
55
565.5 Update READMEs in the main dirac directory.
57
585.6 Check that the contributor database is up to date and that any code that is 
59to be released has been appropriately licensed.
60
615.7 Update NEWS with features added/bugs fixed in the release
62
63Any changes resulting from these checks should be checked into the diracvideo
64GIT repository.
65
666.   Creating and testing the Release
67
68     Once all the above checks have been successful, it is time to create the
69     release.
70
716.1 Ensure that all files are committed into the diracvideo GIT repsitory.
72
736.2 Check out the latest code from the diracvideo GIT repository into 
74a new directory. This is to ensure that all modified/new files have been
75checked in.
76
776.3 Update the release id in configure.ac and commit the changes. Regenerate
78the configure script (./bootstrap)
79
806.4 Compile and test the code again in this directory to ensure that all files
81have been checked in.
82
836.5 Create the distribution using 'make dist'. 
84
856.6 Unpack the distribution and compile and test it (Steps 1 and 2) to ensure 
86that the release distribution has all the necessary files.
87
886.7 Ensure that all the documentation (new READMEs) are present in the release.
89
906.8 Update ChangeLog
91
926.9 Tag all the files with the latest release tag
93
946.10 Repeat Steps 6.2 thru 6.6
95
966.11 Ensure that all mirror sites (e.g. Sourceforge.net/projects/dirac) are 
97     updated.
98
996.11 Upload the distribution to Dirac downloads page on diracvideo.org and 
100     Dirac project page on Sourceforge.
101
1026.12 Recreate the Dirac Directshow filter if required and upload it to Dirac 
103     downloads page on diracvideo.org and Dirac project page on Sourceforge
104
1056.15 Announce the new release by sending an email to the Dirac announce mailing 
106    list dirac-announce@lists.sourceforge.net
107
1086.16 Update News on the diracvideo.org and Dirac project page on Sourceforge.
109
1106.17 Update project page on www.freshmeat.net
111