Credit Andrea - correct HDR references

diff --git a/parts/Introduction.tex b/parts/Introduction.tex
index b9175b95de79f28cd3c32b7f26b509e7fc662fa0..f4f78c03b8d707da56d1dc3433a44da08108e42e 100644 (file)
--- a/parts/Introduction.tex
+++ b/parts/Introduction.tex
@@ -147,8 +147,7 @@ programmers.
                     \item Hardware acceleration with vaapi and vdpau for computers with graphics hardware meeting certain criteria.
                     \item Bump Autos is a new type of keyframe automation that allows you to easily create and manage keyframes intervals in Speed, Fade and Camera/Projector-XYZ curves.
                                         \item One of the only Linux NLEs that handles and renders RGB, 444, 422 and 420 at 8, 10 and more-bit footage as opposed to working in only 8-bit (which introduces some artifacts like banding); both in Full Range Color and limited Broadcast Range Color.
                     \item Hardware acceleration with vaapi and vdpau for computers with graphics hardware meeting certain criteria.
                     \item Bump Autos is a new type of keyframe automation that allows you to easily create and manage keyframes intervals in Speed, Fade and Camera/Projector-XYZ curves.
                                         \item One of the only Linux NLEs that handles and renders RGB, 444, 422 and 420 at 8, 10 and more-bit footage as opposed to working in only 8-bit (which introduces some artifacts like banding); both in Full Range Color and limited Broadcast Range Color.

-                    \item \CGG{} runs internally in 32-bit floating-point and thus can read and process HDR media.
-                    \item The Blend Algebra/Blend Program plugins provide the advanced feature of combining and modifying color pixels and transparencies of several tracks according to a mathematic algorithm written entirely by the user in the form of compact and simple piece of code. Such user defined algorithms (blend functions) are compiled, dynamically linked and immediately executed inside Cinelerra on the fly without the need to restart the application, reload the project, reattach plugins, etc. 
+                     \item The Blend Algebra/Blend Program plugins provide the advanced feature of combining and modifying color pixels and transparencies of several tracks according to a mathematic algorithm written entirely by the user in the form of compact and simple piece of code. Such user defined algorithms (blend functions) are compiled, dynamically linked and immediately executed inside Cinelerra on the fly without the need to restart the application, reload the project, reattach plugins, etc. 

                 \end{itemize}
 \end{description}
 
                 \end{itemize}
 \end{description}
 

diff --git a/parts/Plugins.tex b/parts/Plugins.tex
index b711e39d36a2b02633b9feadb31a24fd46564931..76b61ebb5392a504c373af1b9fcb5a9ac2646bf4 100644 (file)
--- a/parts/Plugins.tex
+++ b/parts/Plugins.tex
@@ -422,10 +422,10 @@ ffmpeg -i /tmp/filename.mpeg -threads 15 -vf format=rgb24,xxxxxxs=threads=8 -aco
 
 This converts the input to rgb before xxxxxx runs, and so it too is slower (because there is more color data). You would ordinarily avoid this conversion by omitting the \texttt{format=rgb24} parameter. An example ffmpeg plugin that could easily take advantage of an auxilliary opts file is \textit{nlmeans}.
 
 
 This converts the input to rgb before xxxxxx runs, and so it too is slower (because there is more color data). You would ordinarily avoid this conversion by omitting the \texttt{format=rgb24} parameter. An example ffmpeg plugin that could easily take advantage of an auxilliary opts file is \textit{nlmeans}.
 

-\subsection{Pipeline HDR and plugins}%
-\label{sub:pipeline_hdr_plugins}
+\subsection{Floating-point pipeline and plugins}%
+\label{sub:pipeline_fp_plugins}

 
 

-\CGG{} runs internally in 32-bit floating-point and thus can read and process HDR media. However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline in HDR. The limited plugins are: \textit{Blur; Color 3 Way} (partially); \textit{Color Space; Foreground; Histogram} (partially); \textit{Histogram Bezier; Title; Videoscope} (partially).
+\CGG{} runs internally in 32-bit floating-point and thus can read and process values outside the range $(0 - 1.0f)$ (\textit{illegal} values, they need the final \textit{conforming} step to comply with the \textit{legal} values). However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline which preserves the original values. The limited plugins are: \textit{Blur; Color 3 Way} (partially); \textit{Color Space; Foreground; Histogram} (partially); \textit{Histogram Bezier; Title; Videoscope} (partially).

 
 \section{Audio Effects - Native}%
 \label{sec:audio_effects_native}
 
 \section{Audio Effects - Native}%
 \label{sec:audio_effects_native}


@@ -1548,7 +1548,7 @@ If you are building an alpha selection mask by first intersection and then union
 \label{sub:blur}
 \index{blur}
 
 \label{sub:blur}
 \index{blur}
 

-This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Motion}, \textit{Radial}, and \textit{Zoom} --are described later. This plugin is keyframable. Blur is used to blur a video track via the following parameters:
+This is a Gaussian type blur. Other blur plugins -- \textit{Linear}, \textit{Motion}, \textit{Radial}, and \textit{Zoom} --are described later. This plugin is keyframable. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping. Blur is used to blur a video track via the following parameters:

 \begin{description}
     \item[Horizontal and vertical] values are used to tell which one of the fields blurring affects; can be both.
     \item[Radius] use this dial to define the amount of blur to apply.
 \begin{description}
     \item[Horizontal and vertical] values are used to tell which one of the fields blurring affects; can be both.
     \item[Radius] use this dial to define the amount of blur to apply.


@@ -1869,7 +1869,7 @@ The most common use cases (but can be adapted to virtually any situation) of the
     \item Create a Stylized look.
 \end{itemize}
 
     \item Create a Stylized look.
 \end{itemize}
 

-When using the X11 graphics driver and RGBA-FLOAT color model, this plugin allows for greater than (0 - 1.0f) values (HDR). This does not work when using X11-OpenGL because it is an 8-bit limited driver. HDR values will only work for the color wheel, while the Value and Saturation sliders are always clipped to 1.0.
+When using the X11 graphics driver and RGBA-FLOAT color model, this plugin allows for greater than (0 - 1.0f) values (\textit{illegal} values). This does not work when using X11-OpenGL because it is an 8-bit limited driver. Illegal values will only work for the color wheel, while the Value and Saturation sliders are always clipped to 1.0f.

 
 \subsection{Color Balance}%
 \label{sub:color_balance}
 
 \subsection{Color Balance}%
 \label{sub:color_balance}


@@ -1894,7 +1894,7 @@ This plugin is a tool that can be used to convert your input media, such as a re
 from one color space/range to another.  It works for both RGB and YUV as set by your project format.
 Options are BT601, BT709, or BT2020 for Color Space input and output and JPEG or MPEG for Color Range
 input and output.  The Inverse option checkbox is available in case your media was rendered in the wrong
 from one color space/range to another.  It works for both RGB and YUV as set by your project format.
 Options are BT601, BT709, or BT2020 for Color Space input and output and JPEG or MPEG for Color Range
 input and output.  The Inverse option checkbox is available in case your media was rendered in the wrong

-color space  or range so that you can fix it.
+color space  or range so that you can fix it. By its nature, this plugin will always cause clipping on values above 1.0f.

 
 \begin{figure}[H]
        \centering
 
 \begin{figure}[H]
        \centering


@@ -2162,8 +2162,7 @@ This effect flips a video track either vertically or horizontally.
 \label{sub:foreground}
 \index{foreground}
 
 \label{sub:foreground}
 \index{foreground}
 

-Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker, color wheel, color presets, or by entering the hexadecimal value.
-In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly.
+Whatever the visual content of the frame, the Foreground plugin application applies a uniform color that can be chosen by color picker, color wheel, color presets, or by entering the hexadecimal value. In addition there are HSV, RGB, YUV, and alpha sliders to vary the color accordingly. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping.

 
 \subsection{Frames to fields}%
 \label{sub:frames_to_fields}
 
 \subsection{Frames to fields}%
 \label{sub:frames_to_fields}


@@ -2452,7 +2451,7 @@ So, by reporting the sum the shape of the results are more similar to Bezier.
 \label{sub:histogram_bezier_curves}
 \index{histogram Bezier}
 
 \label{sub:histogram_bezier_curves}
 \index{histogram Bezier}
 

-Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method (bins). In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions.
+Histogram Bézier allows an immediate view of the contrast amplitude of an image with its distribution of luma and colors values using a piecewise linear method (bins). In addition it uses a Bézier curve (parametric) on the histogram plot. When mapping color spaces, it has a variety of presentations to get smoother transitions and more pleasing output. It uses more general remapping, not just straight lines but more contour lines. Curves are perhaps the most powerful and sophisticated tool for color correction. For some repetitive details, see the previous description of the Histogram plugin. Histogram Bézier is keyframable. The scale is given in percent ($0 - 100\% \pm 10\%$). The default curve is Log type and can use either RGB or YUV sources without implementing conversions. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping.

 
 NOTE: Histogram Bezier may give results that are not congruent with Histogram plugin. To understand the difference in behavior see the Theory section in Histogram plugin.
 
 
 NOTE: Histogram Bezier may give results that are not congruent with Histogram plugin. To understand the difference in behavior see the Theory section in Histogram plugin.
 


@@ -3673,7 +3672,7 @@ It is used to get a timelapse quickly and easily. It sets the number of frames t
 \label{sub:title}
 \index{title}
 
 \label{sub:title}
 \index{title}
 

-The \textit{Titler} allows you to add text from within \CGG{}. It has many configuration capabilities. Often it is convenient to apply the plugin on a separate track (shared or not), in order to make it independent from the video track and have more freedom in editing and configuration. For example, you can apply the \textit{Rotation} plugin to rotate the title without rotating the underlying video. Another thing to keep in mind when using the Titler plugin is that it works on the \textit{temporary} and therefore it is not affected by Camera movements (curves), but only by Projector movements.
+The \textit{Titler} allows you to add text from within \CGG{}. It has many configuration capabilities. Often it is convenient to apply the plugin on a separate track (shared or not), in order to make it independent from the video track and have more freedom in editing and configuration. For example, you can apply the \textit{Rotation} plugin to rotate the title without rotating the underlying video. Another thing to keep in mind when using the Titler plugin is that it works on the \textit{temporary} and therefore it is not affected by Camera movements (curves), but only by Projector movements. If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping.

 
 The titler has standard options for font, size, and style plus many options as described next (figure~\ref{fig:title01})
 
 
 The titler has standard options for font, size, and style plus many options as described next (figure~\ref{fig:title01})
 


@@ -3986,7 +3985,7 @@ Videoscope summarizes intensity and color on a calibrated display. The Videoscop
        \label{fig:videoscope01}
 \end{figure}
 
        \label{fig:videoscope01}
 \end{figure}
 

-When using the X11 graphics driver and RGBA-FLOAT color model, Videoscope allows you to display greater than (0 - 1.0f) values  to accomodate HDR. This does not work when using X11-OpenGL because it is an 8-bit limited driver. The display will stop at -10\% or +110\%, but there is no clipping.  For example, by varying the brightness all out-of-range values become visible on Waveform, even over 110\%. However you must disable the "smooth" option which always causes clipping.
+If the original source has values outside the range $(0 -1.0f)$, the plugin will always produce clipping. The display will stop at -10\% or +110\%, but there is no clipping.  For example, by varying the brightness all out-of-range values become visible on Waveform, even over 110\%. However you must disable the "smooth" option which always causes clipping.

 
 The Videoscope menu window has many options.
 
 
 The Videoscope menu window has many options.
 

diff --git a/parts/Quickstart.tex b/parts/Quickstart.tex
index ade751eba6bc07bce994b9f9fd7b4a8da5424bad..b6ccf66383c49ee060dfad4a756a483ae1eb53dd 100644 (file)
--- a/parts/Quickstart.tex
+++ b/parts/Quickstart.tex
@@ -519,14 +519,15 @@ The camera sensors are always RGB and linear. Generally, those values get conver
 \subsection{HDR}%
 \label{sub:hdr}
 
 \subsection{HDR}%
 \label{sub:hdr}
 

-\CGG{} runs internally in 32-bit floating-point and thus can read and process HDR media. However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline in HDR. The manual indicates which plugins limit pixel values in the range $(0, 1.0)$. The easiest way to see if a media is HDR is to use the \texttt{eyedroppe}r tool (Get Color) in the Compositor window.
+Before 2016, HDR was understood as values outside the range (0 - 1.0f). Since there were no devices capable of achieving these values the only way available was to create digital images (in Blender, for example) or to merge multiple images with various dynamic ranges into a single HDR image. In 2016, with the arrival of sensors and monitors capable of extended dynamic ranges, HDR was standardized and there is the BT. 2100 color space that has gamut and color model like BT. 2020 but different transfer functions (gamma): Dolby Vision (HDR10), PQ and HLG. BT. 2100 considers values above 1.0f as illegal. There are two ways to return to \textit{legal} values: clipping and tone-mapping. The BT.2100 color space is an efficient standard for encoding HDR colors, but it's not well suited for many rendering and composition (blending) operations.
+
+\CGG{} runs internally in 32-bit floating-point and thus can read and process values outside the range $(0 - 1.0f)$. However, there are plugins and tools that can introduce clipping that must be taken into account to keep the whole pipeline which preserves the original values. The manual indicates which plugins limit pixel values in the range $(0, 1.0f)$. The easiest way to see if a media is out of $(0 - 1.0f)$ range is to use the \texttt{eyedropper} tool (Get Color) in the Compositor window.

 If we use HDR media and need to do a Tone Mapping to make the pixel values fall within the range $(0, 1.0)$, we can use the \texttt{Blender Program} plugin and, inside it, load the function (found in \texttt{=>Syslib}) \textit{tone\_mapping.bp}. Instructions for using this function can be found \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples/Examples.txt}{here} at example 6.
 
 \subsection{CMS}%
 \label{sub:cms}
 
 If we use HDR media and need to do a Tone Mapping to make the pixel values fall within the range $(0, 1.0)$, we can use the \texttt{Blender Program} plugin and, inside it, load the function (found in \texttt{=>Syslib}) \textit{tone\_mapping.bp}. Instructions for using this function can be found \href{https://cinelerra-gg.org/download/testing/BlendPluginExamples/Examples.txt}{here} at example 6.
 
 \subsection{CMS}%
 \label{sub:cms}
 

-A color management system (CMS) describes how it translates the colors of images/videos from their current color space to the color space of the other devices, i.e. monitors. The basic problem is to be able to display the same colors in every device we use for editing and every device on which our work will be viewed. Calibrating and keeping our hardware under control is feasible, but when viewed on the internet or DVD, etc. it will be impossible to maintain the same colors. The most we can hope for is that
-there are not too many or too bad alterations. But if the basis that we have set up is consistent, the alterations should be acceptable because they do not result from the sum of more issues at each step. There are two types of color management: \textit{Display referred} (DRC) and \textit{Scene referred} (SRC).
+A color management system (CMS) describes how it translates the colors of images/videos from their current color space to the color space of the other devices, i.e. monitors. The basic problem is to be able to display the same colors in every device we use for editing and every device on which our work will be viewed. The color management operation consists of a color space conversion (matrix and 1DLUT). Colors that exceed the display's target color gamut are numerically clipped. Calibrating and keeping our hardware under control is feasible, but when viewed on the internet or DVD, etc. it will be impossible to maintain the same colors. The most we can hope for is that there are not too many or too bad alterations. But if the basis that we have set up is consistent, the alterations should be acceptable because they do not result from the sum of more issues at each step. There are two types of color management: \textit{Display referred} (DRC) and \textit{Scene referred} (SRC). Display-refered: 1.0f (white point) as the reference white level of the display. Scene-refered: 1.0f as the reference white of the used Color Space (nominal)

 
 \begin{itemize}
        \item \textbf{DRC} is based on having a calibrated monitor. What it displays is considered correct and becomes the basis of our color grading. The goal is that the colors of the final render will not change too much when displayed in other hardware/contexts. Be careful to make sure there is a color profile for each type of color space you choose for your monitor. If the work is to be viewed on the internet, be sure to set the monitor in \textit{sRGB} with its color profile. If for HDTV we have to set the monitor in \textit{rec.709} with its color profile; for 4k in \textit{Rec 2020}; for Cinema in \textit{DCP-P3}; etc.
 
 \begin{itemize}
        \item \textbf{DRC} is based on having a calibrated monitor. What it displays is considered correct and becomes the basis of our color grading. The goal is that the colors of the final render will not change too much when displayed in other hardware/contexts. Be careful to make sure there is a color profile for each type of color space you choose for your monitor. If the work is to be viewed on the internet, be sure to set the monitor in \textit{sRGB} with its color profile. If for HDTV we have to set the monitor in \textit{rec.709} with its color profile; for 4k in \textit{Rec 2020}; for Cinema in \textit{DCP-P3}; etc.