"Fossies" - the Fresh Open Source Software Archive

Member "darktable-3.6.1/doc/pdf/hacking.tex" (10 Sep 2021, 12723 Bytes) of package /linux/misc/darktable-3.6.1.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \documentclass[a4paper,twoside]{scrartcl}
    2 
    3 \usepackage{graphicx,color}
    4 \graphicspath{{images/}{../htdocs/images/header/}}
    5 
    6 \usepackage{mparhack}
    7 
    8 % \usepackage[a4paper]{geometry}
    9 % \geometry{%
   10 % twoside,%
   11 % %height=.7\paperheight,%
   12 % %width=.7\paperwidth,%
   13 % top=.1\paperheight,%
   14 % bottom=.2\paperheight,%
   15 % left=.1\paperwidth,%
   16 % right=.2\paperwidth%
   17 % %bindingoffset
   18 % }
   19 
   20 \usepackage{fancyhdr}
   21 \pagestyle{fancy}
   22 \fancyhead{}
   23 \fancyfoot{}
   24 \fancyfoot[LE,RO]{\iffloatpage{}{\thepage}}
   25 \renewcommand{\headrulewidth}{0pt}
   26 \renewcommand{\footrulewidth}{0pt}
   27 \setlength{\oddsidemargin}{.1\paperwidth}
   28 \setlength{\evensidemargin}{.2\paperwidth}
   29 \setlength{\headheight}{.1\paperheight}
   30 \setlength{\headsep}{0pt}
   31 \setlength{\topmargin}{0pt}
   32 \setlength{\voffset}{-1in}
   33 \setlength{\hoffset}{-1in}
   34 \setlength{\textwidth}{.7\paperwidth}
   35 \setlength{\textheight}{.7\paperheight}
   36 \setlength{\marginparwidth}{.1\paperwidth}
   37 
   38 \newcommand{\nicesection}[2]{%
   39 \cleardoublepage
   40 \fbox{\includegraphics[width=\linewidth]{#1}}%
   41 \vspace*{-1em}%
   42 \section{\hfill #2}
   43 \hrule
   44 \vspace*{\baselineskip}%
   45 }
   46 
   47 \fboxsep0pt
   48 \setlength{\parindent}{0pt}
   49 
   50 \newcommand{\todo}[1]{{\color{red}\bf TODO: #1}}
   51 \newcommand{\comment}[1]{}
   52 \definecolor{codecol}{rgb}{0.1,0.2,0.5}
   53 \newcommand{\code}[1]{\texttt{\color{codecol}#1}}
   54 
   55 \frenchspacing
   56 % \usepackage[T1]{fontenc}
   57 % \usepackage[condensed,math]{iwona}
   58 
   59 %\usepackage[T1]{fontenc}
   60 %\usepackage[urw-garamond]{mathdesign}
   61 
   62 \usepackage[T1]{fontenc}
   63 \usepackage[scaled]{helvet}
   64 \renewcommand{\familydefault}{\sfdefault}
   65 
   66 %\setkomafont{sectioning}{\sfdefault}
   67 
   68 
   69 \title{darktable Programmer's Guide}
   70 \author{hanatos}
   71 
   72 \begin{document}
   73 
   74 \fbox{\includegraphics[width=\linewidth]{header12}}%
   75 \vspace*{-1em}%
   76 \section*{\hfill darktable Programmer's Guide}
   77 \hrule
   78 
   79 \vspace*{4\baselineskip}
   80 
   81 {\hfill version \input version.tex }
   82 
   83 \thispagestyle{empty}
   84 
   85 \newpage
   86 \tableofcontents
   87 
   88 
   89 \nicesection{header1}{Introduction}
   90 \label{sec:introduction}
   91 
   92 
   93 \nicesection{header2}{System Layout}
   94 
   95 \resizebox{\linewidth}{!}{\input{graphs/system.pdftex_t}}
   96 
   97 \subsection{Module Descriptions}
   98 
   99 \begin{description}
  100   \item[gui] using gtk2 and cairo.
  101 \end{description}
  102 \begin{description}
  103   \item[control]
  104   \item[control, scheduler] using pthreads and a custom job queuing system.
  105 \end{description}
  106 \begin{description}
  107   \item[image]
  108   \item[image cache]
  109   \item[mipmap cache]
  110   \item[db]
  111   \item[imageio]
  112 \end{description}
  113 \begin{description}
  114   \item[library] this is the lighttable module.
  115   \item[film]
  116 \end{description}
  117 \begin{description}
  118   \item[develop] this implements the darktable.
  119   \item[pixelpipe]
  120   \item[image operation (iop) modules, aka plug-ins]
  121 \end{description}
  122 
  123 \newpage
  124 \subsection{Image Loading Data Flow}
  125 
  126 \paragraph{Related Modules}
  127 \begin{itemize}
  128   \item imageio \code{dt\_imageio\_*}
  129   \item db (messily hidden in sqlite3 statements all over the place)
  130   \item image cache \code{dt\_image\_cache\_*}
  131   \item mip cache \code{dt\_mipmap\_cache\_*}
  132   \item image \code{dt\_image\_t}
  133 \end{itemize}
  134 
  135 \paragraph{in image cache}
  136 \begin{itemize}
  137   \item \code{dt\_image\_import}
  138 
  139   db $\rightarrow$ image struct, trigger imageio disk $\rightarrow$ image entry in db if miss,
  140                 metadata through libraw/magick
  141   
  142  
  143 \end{itemize}
  144 
  145 \paragraph{in mip cache}
  146 \begin{itemize}
  147   \item \code{dt\_image\_get}
  148 
  149       db $\rightarrow$ mip[0--4], trigger imageio disk $\rightarrow$ mip4 and mip4 $\rightarrow$ mip[0-3] if miss.
  150 
  151   
  152       db $\rightarrow$ mipf, trigger mip4 $\rightarrow$ mipf or pixels $\rightarrow$ mipf if miss.
  153 \end{itemize}
  154 
  155 \paragraph{in imageio}
  156 \begin{itemize}
  157   \item \code{dt\_imageio\_open\_preview}
  158 
  159     disk $\rightarrow$ mip[0--4] entries in db (load thumbnail).
  160     \begin{itemize}
  161       \item[\todo{}]  \code{dt\_imageio\_open\_ldr\_preview}
  162       \item \code{dt\_imageio\_open\_raw\_preview}
  163     \end{itemize}
  164   \item mip4 $\rightarrow$ mipf (by guessed reverse gamma) \code{dt\_image\_preview\_to\_raw}.
  165   \item full pixels $\rightarrow$ mipf (downscaling) \code{dt\_image\_raw\_to\_preview}.
  166   \item mip4 $\rightarrow$ mip[0--3] \code{dt\_image\_update\_mipmaps}.
  167 \end{itemize}
  168 
  169 image import: only load \code{dt\_image\_t} and mip[0--4] to database.
  170 
  171 \code{dt\_image\_get}: check mipmap cache, check database, else \code{dt\_imageio\_open[\_preview]}.
  172 
  173 The buffers are as follows:
  174 
  175 \begin{description}
  176   \item[\code{DT\_IMAGE\_MIP0-4}] are used for rendering in light table mode. These are either loaded from the embedded
  177     thumbnail in the raw files (if the \code{never\_use\_embedded\_thumb} key is not set), or store small versions of
  178     processed buffers.
  179 
  180     The function \code{dt\_imageio\_open\_preview} will fill these low-dynamic range buffers ready for display. If a history
  181     stack is present (i.e.\ the image is {\em altered}), this function will load \code{MIPF} instead.
  182 
  183   \item[\code{DT\_IMAGE\_MIPF}] is used by the preview pipe or by pipelines spawned by the light table when creating
  184     \code{DT\_IMAGE\_MIP0-4}. It stores a capped-size four float per pixel representation of the input image.
  185 
  186     This buffer is needed to reduce the overall mem requirements and still process multiple thumbnails of large images
  187     in parallel. darktable rather stores and prefetches a few low-resolution \code{MIPF} buffers instead of full images.
  188 
  189     \code{MIPF} can never be explicitly loaded.
  190 
  191     \code{MIPF} are written if a prefetch is requested for fast darkroom mode entering later on, or by \code{dt\_imageio\_open\_preview}
  192     if the image is altered. It is also written if a full image is requested, to avoid duplicate file accesses in this case.
  193 
  194   \item[\code{DT\_IMAGE\_FULL}] is the full image buffer as read from disk. That is, raw images will store one \code{uint16\_t}
  195     per pixel, mosaiced input data, while high dynamic range input will result in a four float buffer.
  196 
  197 \end{description}
  198 
  199 
  200 \newpage
  201 \subsection{Cache Interfaces}
  202 
  203 \subsubsection{Image Cache}
  204 
  205 \code{dt\_image\_cache\_t}
  206 
  207 \subsubsection{Mipmap Cache}
  208 
  209 \code{dt\_image\_t}
  210 
  211 \begin{description}
  212   \item{\code{dt\_image\_get}} get buffer or, if missed, a lower resolution (launch job in bg for correct resolution)
  213   \item{\code{dt\_image\_load}} Load buffer in this thread, return exactly this resolution.
  214     No locking is performed, so be sure to acquire the lock using \code{dt\_image\_alloc} before.
  215 \end{description}
  216 
  217 \subsubsection{Homebrew Pixelpipe Cache}
  218 
  219 \newpage
  220 \subsection{Plug-in Interface}
  221 
  222 For examples, have a look at \code{src/iop/*.\{h,c\}}, and also see the method declarations in \code{src/common/imageop.h}.
  223 
  224 Pixel processing is done in pipelines (\code{src/develop/pixelpipe\_hb.c}) with fixed order of the modules,
  225 observe the current status with e.g.
  226 
  227 \code{grep priority src/iop/*.c | sort -t '=' -k 2}.
  228 
  229 At the time of this writing, the main pixel pipeline stack is organised as follows:
  230 
  231 \medskip
  232 
  233 \begin{tabular}{lrl}
  234 module name & priority & input color format \\
  235 \hline
  236 rawimport      &  100  &  - \\ 
  237 exposure       &  150  &  fff input color space \\
  238 temperature    &  200  &  fff input color space \\
  239 highlights     &  250  &  fff input color space \\
  240 basecurve      &  260  &  fff input color space \\
  241 profile\_gamma &  299  &  fff input color space \\
  242 colorin        &  300  &  fff input color space \\
  243 colortransfer  &  350  &  fff $L^*a^*b^*$ \\
  244 equalizer      &  500  &  fff $L^*a^*b^*$ \\
  245 monochrome     &  550  &  fff $L^*a^*b^*$ \\
  246 tonecurve      &  700  &  fff $L^*a^*b^*$ \\
  247 colorzones     &  750  &  fff $L^*a^*b^*$ \\
  248 colorcorrection&  800  &  fff $L^*a^*b^*$ \\
  249 colorout       &  900  &  fff $L^*a^*b^*$ \\
  250 lens           &  940  &  fff output color space \\
  251 clipping       &  950  &  fff output color space \\
  252 grain          &  965  &  fff output color space \\
  253 clahe          &  966  &  fff output color space \\
  254 velvia         &  967  &  fff output color space \\
  255 splittoning    &  968  &  fff output color space \\
  256 vignette       &  970  &  fff output color space \\
  257 sharpen        &  990  &  fff output color space \\
  258 gamma          & 1000  &  fff output color space \\
  259                &   -   &  ccc output color space \\
  260 \end{tabular}
  261 
  262 \medskip
  263 
  264 where fff is $3\times32$ bit float, ccc is $3\times8$ bit int, and the input
  265 color space depends on your camera or type of input data, and the output color space will
  266 be sRGB (including gamma correction, i.e.\ it is non-linear) most of the time.
  267 
  268 $L^*a^*b^*$ is a special variant of $L^*ab$, where $L^* \in [0, 100]$ and $a, b \in [-128, 128]$, but $a^* = a/L^*$ and $b^* = b/L^*$.
  269 This makes sure that changes in $L^*$ transparently result in the correct adjustment in saturation:
  270 $a_{out} = a_{in} \cdot L^*_{out}/L^*_{in}$ and
  271 $b_{out} = b_{in} \cdot L^*_{out}/L^*_{in}$.
  272 
  273 
  274 Each module has to implement a \code{process} function, which is responsible for processing of three types of
  275 pipelines: preview, full, and export. Most of the time, this can be handled transparently, i.e.\ needs no special
  276 handling in the module. The pipelines are as follows:
  277 
  278 \begin{description}
  279   \item[preview] all of the image, but downsampled to low resolution for the navigation view, approximate full image statistics, and fast scrolling.
  280   \item[full] full resolution, but only the part that can currently be seen (the region of interest, roi, will be adjusted accordingly).
  281   \item[export] full image at full resolution, no gui data is inited for the module.
  282 \end{description}
  283 
  284 and can be identified by the pipeline struct, which carries a \code{pipe->type} flag. This struct can in turn be found
  285 via the pipeline data piece which is passed to \code{process}: \code{piece->pipe}.
  286 
  287 \paragraph{Regions of Interest}
  288 
  289 A region of interest holds $x,y,w,h$, and scale information. The semantics are as follows: multiply the whole resolution image by
  290 the scale value, then crop it to the window defined by $x, y, w, h$. The passed input buffer will be a contiguous block of values as defined by
  291 the input color space, pixel by pixel and row by row. The output buffer should be in the same format, but the extent should match the
  292 output region of interest.
  293 
  294 
  295 \subsubsection{Most important Gui Callbacks}
  296 
  297 \begin{description}
  298   \item \code{gui\_init} gui thread, init the widget (not called for export)
  299   \item \code{gui\_update} gui thread, make the gui match the modules parameters (not called for export)
  300   \item \code{commit\_params} core thread + gui thread in synch, copy module->params to module->data
  301   \item \code{process} core thread, execute the op on the input buffer
  302   \item \code{modify\_roi\_in}
  303   \item \code{modify\_roi\_out} core thread, optional, only needed if input and output buffers are of different size.
  304     For examples, see \code{src/iop/lens.c} and \code{src/iop/clipping.c}.
  305 \end{description}
  306 
  307 \subsubsection{Data Structures}
  308 
  309 \begin{description}
  310   \item[\code{dt\_iop\_*\_params\_t module->\{params, default\_params, factory\_params\}}]
  311 
  312   This struct should only be modified by the gui thread. The three fields exist only once per module: \code{params}
  313   store the currently active parameters, \code{default\_params} are the default parameters (possibly adjusted by the
  314   user), and \code{factory\_params} are dt's factory defaults (automatically copied by the core after \code{init} has been
  315   called).
  316 
  317   Also, don't store pointers to additional memory in this struct. It will be
  318   stored in the database as blob and copied byte-wise as you defined it. This
  319   means that your pointer will point to garbage memory after leaving/re-entering
  320   darkroom mode, or during export.
  321 
  322   \item[\code{dt\_iop\_*\_data\_t piece->data}]
  323   This struct lives in pixel pipeline domain, and thus exists once for the full and once for the preview pipeline.
  324   It should only be modified by the core thread (which calls \code{commit\_params} and \code{process}).
  325 
  326   \item[\code{dt\_iop\_*\_gui\_data\_t module->gui\_data}]
  327   You can use this struct to store your gui data (from the gui thread, obviously). It exists once per module and should be inited in \code{gui\_init} and
  328   cleaned up in \code{gui\_cleanup}. Note that gtk+ widgets are cleaned up implicitly while the widget is destroyed.
  329 
  330   \item[\code{dt\_iop\_*\_global\_data\_t module->data}]
  331   Core thread global data for all pipes (such as lensfun description database).
  332 \end{description}
  333 
  334 
  335 \subsubsection{A most useless Example}
  336 
  337 
  338 \todo{script to generate as up-to-date minimal dt header set to compile external plugins}
  339 
  340 \todo{a silly template module line by line: render a checker board on top of your input image.}
  341 
  342 See \code{src/iop/useless.c}.
  343 
  344 Change \code{src/iop/Makefile.am}:
  345 \begin{verbatim}
  346 libuseless_la_SOURCES=useless.c
  347 dtplugins_LTLIBRARIES=libtonecurve.la [..] libcolortransfer.la libuseless.la
  348 \end{verbatim}
  349 
  350 \end{document}