NotZed's Source Code Repository - jjmpeg/blob - README

   1
   2 Copyright (C) 2017-2019 Michael Zucchi
   3
   4 See the section LICENSE for details.
   5
   6 Introduction
   7 ------------
   8
   9 jjmpeg is a JNI based Java binding for the suite of libraries provided
  10 by FFmpeg.
  11
  12 The original version of jjmpeg was released sometime in the distant
  13 past and has slowly got further and further behind the current FFmpeg
  14 version.  This is a completely new implementation intended as a
  15 project to catch up with the current API.
  16
  17 Compile
  18 -------
  19
  20 jdk (javac, jar) and native compiler tools (GNU make, cc, cpp, perl)
  21 must be in path.  In addition the program cproto must be installed.
  22 JDK 13 is the baseline but JDK 9+ may work.
  23
  24 The prequisitve project notzed.nativez must also have previously been
  25 compiled and will be automatically used if it is present in the
  26 directory above this one (../nativez/).
  27
  28 First copy config.make.in to config.make and adjust configuration
  29 parameters.
  30
  31 Build everything for default target of linux-amd64:
  32
  33 $ make
  34
  35 Build everything for a specific target:
  36
  37 $ make TARGET=<target>
  38
  39 All intermediate and final results are place in `bin/'.
  40
  41 `bin/<target>/lib/<module>.jar'    Modular jar for ide.
  42 `bin/<target>/lib/*.so'            Platform specific
  43 `bin/<target>/bin/*.dll'            runtime libraries.
  44
  45 `bin/<target>/jmods/<module>.jmod' Target specific .jmod.
  46
  47 $ make bin
  48
  49 Build everything but the jars and jmods.
  50
  51 $ make dist
  52
  53 Create a source archive.  The source is found via $(find) so
  54 this will include any droppings.
  55
  56 NetBeans
  57 --------
  58
  59 Before the source can be easily edited in NetBeans one must
  60 first run the makefile to generate any auto-generated files.
  61
  62 $ make gen
  63
  64 This needs to be done each time `make clean' is executed or
  65 files in `src/notzed.jjmpeg/gen' are edited.
  66
  67 Development
  68 -----------
  69
  70 Some notes on internals.
  71
  72 Java Native Interface
  73 - - - - - - - - - - -
  74
  75 All jj-*.c files are independent of one another, they may only
  76 reference functions and variables from jjmpeg.c.
  77
  78 The native interface is implemented using the notzed.nativez project.
  79 This allows it to support full garbage collection of all relevant
  80 objects.  In some cases this currently requires references to be
  81 manually kept to ensure they survive for the relevant C side objects.
  82 All objects are unique (and keyed) based on their C pointer address.
  83
  84 If used with care, objects can also be manually released safely.
  85
  86 Unlike earlier versions of jjmpeg, version 3+ is implemented almost
  87 entirely using hand-rolled Java and macro-assisted C source-code.
  88 Also unlike earlier versions almost all code is written directly in C
  89 with only skeleton Java wrappers of native method signatures.  This
  90 requires less work and produces smaller code than previous versions.
  91
  92 To further reduce code-size most initialisation is implemented via
  93 tables.
  94
  95 Enumerations
  96 - - - - - -
  97
  98 A set of small(ish) perl scripts are used to extract various
  99 enumeration and #define tables directly from the FFmpeg development
 100 header files.  They generate interfaces which are "implemented" to add
 101 the defines to the desired structures.  These reside in the scripts
 102 directory.
 103
 104 All enumerations were converted to final integer values for
 105 consistency.  Where the corresponding functions exist, static
 106 valueOf() and toString() are available for obvious purposes.
 107
 108 The perl scripts generate C code which is then compiled and executed
 109 to create the Java interfaces.
 110
 111 Exceptions
 112 - - - - -
 113
 114 Exceptions fall into two categories, AVIOException and AVException,
 115 both checked exceptions.  The former derives from IOException for
 116 simplicity.
 117
 118 They contain the error code (errno and AVERROR defines) and a
 119 description.
 120
 121 Where it makes sense other Java checked and unchecked exceptions such
 122 as FileNotFoundException or OutOfMemoryError are also thrown.
 123
 124 Linkage
 125 - - - -
 126
 127 All libraries are dynamically linked at runtime.  Missing functions
 128 result in an initialisation failure.
 129
 130 Method signatures are automatically extracted from headers via the
 131 script src/notzed.jjmpeg/jni/extract-proto.pl based on per-file .def
 132 files.  This also generates a table for initialising the pointers.
 133
 134 Build System
 135 - - - - - -
 136
 137 See java.make.  It's a lot simpler than it looks and is based on
 138 meta-make programming via macros and pattern variables.
 139
 140 Documentation
 141 - - - - - - -
 142
 143 Very lacking, but at least most of the enumerations now have the
 144 comments present in the header files.
 145
 146 Status
 147 ------
 148
 149 Enough core classes to read and write video frames is implemented as
 150 well as a pair of high-level interfaces JJMediaReader and
 151 JJMediaWriter.  These have been simplified somewhat from the previous
 152 implementation, but it takes less code to use them anyway.
 153
 154 Most functions that should throw exceptions do although that which
 155 they throw may be tweaked.
 156
 157 Many accessors have been implemented, in some cases they have been
 158 Javaised or NotZedised (e.g. setFlags(mask, value)) for a cleaner
 159 interface.  Because of the complexity of the libraries and objects it
 160 is not always clear which members need to be accessed by user code so
 161 some of the choices are arbitrary.  Or I just gave up part way
 162 through.  They are easy to add.
 163
 164 There are two sub-modules notzed.jjmpeg.fx and notzed.jjmpeg.awt which
 165 supply the JavaFX and Swing/AWT specific functionality.
 166
 167 See also TODO.
 168
 169 Compatibility
 170 -------------
 171
 172 This version is compatible with at least version 4.0 of FFmpeg.
 173
 174 No deprecated functions or fields have been made accessible from Java
 175 or are used in the native code.
 176
 177 To support contrib/octave the main source-code (sans the module-info
 178 files) is limited to Java 8.
 179
 180 Links
 181 -----
 182
 183 * nativez <https://www.zedzone.space/software/nativez.html>
 184 * jjmpeg  <https://www.zedzone.space/software/jjmpeg.html>
 185 * FFmpeg  <http://www.ffmpeg.org/>
 186 * OpenJDK <http://openjdk.java.net/>
 187
 188 LICENSE
 189 -------
 190
 191 Most of the code is licensed under GNU General Public License version
 192 3, see src/<module>/legal/LICENSE for the full details for each module.
 193
 194     Copyright (C) 2017-2019 Michael Zucchi
 195
 196     This program is free software: you can redistribute it and/or
 197     modify it under the terms of the GNU General Public License as
 198     published by the Free Software Foundation, either version 3 of the
 199     License, or (at your option) any later version.
 200
 201     This program is distributed in the hope that it will be useful,
 202     but WITHOUT ANY WARRANTY; without even the implied warranty of
 203     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 204     General Public License for more details.
 205
 206     You should have received a copy of the GNU General Public License
 207     along with this program.  If not, see
 208     <http://www.gnu.org/licenses/>.
 209
 210 Portions are auto-generated from FFmpeg header files and are thus
 211 copyright various authors but are also distributed under the GNU
 212 General Public License Version 3 (or later) as per the copyright
 213 header permissions.
 214
 215 These portions are clearly marked in the bin/gen/*Bits.java files.