From 83c3752b99e485c665c1662c95f2700278db4bf8 Mon Sep 17 00:00:00 2001 From: Good Guy Date: Sat, 22 Feb 2025 18:27:53 -0700 Subject: [PATCH] Credit SGE - Blend Algebra and Blend Program documentation --- cinelerra-5.1/doc/Makefile | 1 + cinelerra-5.1/doc/README.blendalg | 877 ++++++++++++++++++++++++++++++ cinelerra-5.1/msg/txt | 4 + 3 files changed, 882 insertions(+) create mode 100644 cinelerra-5.1/doc/README.blendalg diff --git a/cinelerra-5.1/doc/Makefile b/cinelerra-5.1/doc/Makefile index 25cc9d34..776447e1 100644 --- a/cinelerra-5.1/doc/Makefile +++ b/cinelerra-5.1/doc/Makefile @@ -59,6 +59,7 @@ install: all cp -a shortcuts.html $(TARGET_DIR)/. cp -a RenderMux.sh $(TARGET_DIR)/. cp -a ContextManual.pl $(TARGET_DIR)/. + cp -a README.blendalg $(TARGET_DIR)/. cp -a 99-ShuttlePRO.rules $(TARGET_DIR)/. clean: diff --git a/cinelerra-5.1/doc/README.blendalg b/cinelerra-5.1/doc/README.blendalg new file mode 100644 index 00000000..4622d678 --- /dev/null +++ b/cinelerra-5.1/doc/README.blendalg @@ -0,0 +1,877 @@ + Introduction + ============ + +Both plugins, Blend Algebra and Blend Program, are similar. I'll describe +them together, pointing to differences where they come. + +The essential object which defines, what actually takes place inside the +plugin, is the piece of code, typically written by the user. Throughout the +description I will use the word 'function' to denote this object for any of +the two plugins. + +Actually, Blend Algebra and Blend Program functions are ELF shared objects +(see `man dlopen', `man dlsym') dynamically compiled and linked to the +corresponding plugin in run time. These functions are for their plugins +same as the plugin shared objects themselves for the main Cinelerra binary. +But unlike the complex plugins, these functions are so simple that can be +easily written by users and manipulated not only in binary, but also in +source forms. + +An experienced user can have a number of such functions reused in many +projects. Therefore having a user library of functions as well as a system +library can be handy. This feature is provided by the plugins. + +The functions work on individual pixels, one pixel at a time from all the +tracks the plugin is attached to. Pixels are passed to functions in forms +of color components in a definite color space. How exactly it is done, see +the description later. + +The main difference between the two plugins is the following. + +Blend Algebra is like a function: it combines its input arguments (tracks) +and yields the result which is placed into the single track configured for +output. + +Blend Program does not produce a function result. Instead, it directly +modifies its arguments (like a void function with side effect in C). + +Which one should be used? + +If more than one track is to be modified, Blend Program is the only choice. + +If only one single track is to be processed, perhaps Blend Program would +present more natural approach, and might compute slightly faster. + +Any Blend Algebra function can be rewritten to become a Blend Program +function. But if a function processes several tracks and modified only one, +it will run faster in Blend Algebra form, and will get a few additional +controls in the Blend Algebra plugin dialog. + +The plugin is attached to a track as usual. Generally, it needs several +tracks as arguments. If so, it has to be attached to that additional tracks +as a shared effect, as usual for multitrack plugins. + + Blend Algebra / Blend Program GUI + ================================= + +All the parameters described below are keyframable, including user functions +themselves. + +The top area of the dialog deals with programmatic aspects. +----------------------------------------------------------- + +Program: (Function:) +-------------------- + +Here is the filename of the user's function source text. Although most +convenient method to select the function is via the Attach... dialog, it is +possible to enter its filename here directly. If the function pathname does +not start with '/', it is interpreted relative to the main project +directory. Empty function name means that no function will be executed +here, the tracks will remain unchanged. If the entered filename does not +exist, also nothing will be done (but in this case the user can create +source file via the Edit... button). + +Although entering any filename is possible here, it is highly recommended to +use distinct suffixes: .ba for Blend Algebra, .bp for Blend Program. + +Attach... +--------- + +This button opens the file selection dialog typical of Cinelerra. By +default it shows only files with the proper suffixes (*.ba or *.bp), +although this can be changed by specifying filter. As usual, the user can +select an existing file, or enter filename directly. The user can exit the +dialog with Cancel (changing nothing) or with OK. In the latter case, the +selected function will be set as current, and its name will appear in the +Program: text field above. + +If the entered filename does not end with .ba (.bp), the corresponding +suffix will be appended automatically. If the user for some reason has to +use filename with another or no suffix (which is not recommended), he has to +change the name directly in the Program: input field after exiting file +selection. + +The file selection dialog has six additional buttons specific to Blend +Algebra / Blend Program. + +The three buttons on top left change the current directory: + +=>Project - go to the project directory (where the main project .xml file +resides). + +=>Userlib - go to user library. + +=>Syslib - go to system library. + +The three buttons on bottom left do simple file operations: + +Copy to project - copies the currently selected function source file in the +project directory. + +Copy to userlib - copies the currently selected function source file to user +library. There is no button to copy a function into the system library +because the system library is meant for functions distributed with +Cinelerra, which can get overwritten on reinstallation or upgrade. + +What copying to/from project, userlib, or syslib is used for, see the +section 'User library, system library, and Cinelerra project directories' +below. + +Edit... +------- + +Open the currently selected function source file in the configured external +editor. Which editor will be used, is defined by the environment variable +$CIN_EDITOR. It must be a windowed editor, like GNU Emacs, or KDE's Kate, +or Nedit, or ancient Xedit, not a bare console editor like vi. If you wish +to use a console editor, it must be defined to run in a terminal emulator, +like xterm, or KDE's Konsole, for example: + +export CIN_EDITOR='konsole -e vi' +cin + +Currently, emacs is defined as the default text editor (if CIN_EDITOR is not +set). Which one should better be used by default? A good question... Is +there a text editor which is guaranteed to exist in any Linux distribution? +It might be vi, but then we need a guaranteed terminal emulator. Xterm? +Isn't there a distribution where there is no xterm? Konsole? But if a +distribution is not KDE based, but GNOME based, there may be no Konsole... +OK, at least GNU Emacs is well known since the last millennium, therefore +let it be emacs for now. + +To open editor from the plugin dialog, some function must be selected in the +file selection dialog, or active at that timeline position (its name in text +field not empty). Either select some existing function first or enter a +name to create a new one from scratch, otherwise an error message is printed +and editor not started. + +The same button 'Edit...' exist also in the main plugin dialog, for the same +purposes. + +Other buttons are the same as in any regular file selection dialog, to +change directory, delete or rename a file, etc. These common buttons are +not described here. + +Refresh +------- + +External editor, after pressing the Edit... button, is started in +background. After having edited and saved a function, the user may leave +editor on screen. Moreover, the user can edit a function externally, not +from inside Cinelerra at all. In order not to check modification times of +all the functions on each video frame, Cinelerra has to know when a function +can get changed. Pressing Refresh signals Cinelerra, there is time to check +functions, and eventually to recompile some of them. + +How and under which conditions the functions are recompiled, see the +description below. + +Detach +------ + +This button clears the function name in the Program: input field, which +means that no function will be used here, the tracks to which the plugin is +attached will remain unchanged. + +Color space: +------------ + +Here is defined, in which color space the frame pixels are to be passed to +the function. The RGB, YUV, and HSV color spaces are supported. The most +often used, and the default, is the choice 'auto', it means working in that +color space which is required by the function itself. The fifth choice, 'of +project', means to work in the native color space of the project (as defined +in Settings->Format). If the required color space does not match the native +one, pixel color components will be transformed to the required space, as +floating point numbers. After returning from the function, pixels of the +result will be transformed back to the native color space of the project. + +Parallelize processing +---------------------- + +This checkbox (on by default) lets to execute user function code in +parallelized (multithreading) manner, provided that the function itself +supports this. How exactly the function code is executed, see the +description later. + +The middle area of the dialog is color specific. +------------------------------------------------ + +Inside the user written code, some illegal floating point operations may +occur, like division by zero (producing Infinity), or square root from minus +unity (producing NaN, not-a-number). Even if only legal, finite floating +point numbers are computed, the results may go out of bounds. This dialog +section controls, what to do in such cases. + +Clip color values +----------------- + +If this checkbox is on (the default), the function results first of all will +be clipped to bounds. Clipping takes place before back transformation to +the project color space. The bounds are defined as follows: + +RGB: [0.0 .. 1.0] for R, G, B +YUV: [0.0 .. 1.0] for Y, [-0.5 .. +0.5] for U, V +HSV: [0.0 .. 360.0] for H, [0.0 .. 1.0] for S, V +Transparency: [0.0 .. 1.0] for Alpha + +'H' color channel of HSV is brought into bounds trigonometrically by +repeated rotation around 360 degrees, all the others by simple arithmetic +clipping. + +If the project color space is RGB(A)-8 Bit or YUV(A)-8 Bit, clipping occurs +unconditionally because of intrinsically restricted dynamic range of 8-bit +storage per channel. For RGB(A)-FLOAT clipping can be switched off. What +occurs with unclipped pixels later, depends on further destinations in the +Cinelerra video processing pipeline. Moreover, display drivers react on +unclipped colors differently. For example, an RGB pixel with unclipped red +component R=-1.0 and two other components G=B=0.0 is displayed as black +(i.e. with R clipped to zero) by the OpenGL driver, but as red (i.e. taken +with opposite sign) by the X11 driver. Explicit clipping in the plugin +itself allows to eliminate such driver dependency. + +Chroma key or substitution color: +--------------------------------- + +Even after (optional) clipping, there can still remain some non-finite +results, like NaN. Such results are highly undesired and should be +eliminated as soon as possible. If any of color components, or alpha +channel, is NaN, this complete pixel (all 4 components) is replaced with the +configured color and the configured opacity. + +Select key color... +------------------- + +This button opens Cinelerra color selection dialog to select the color which +will be used as substitution for NaNs or infinities in the results. + +Get from color picker +--------------------- + +With this button the user can copy the color fetched earlier in the color +picker tool of the Cinelerra Compositor window. + +Substitution opacity: +--------------------- + +This slider sets the opacity (alpha-channel) value to be used together with +substitution color. + +Substitution color and opacity are passed as additional arguments to user +functions and can be 'mis-used' there for more or less artistic purposes, +such as chroma keying. + +The bottom area of the dialog has controls for the argument track ordering, +similar to that of the well known Overlay plugin. + +Track order: +------------ + +If the plugin is attached to N tracks, its user functions get pixels of that +tracks numbered from 0 to N-1 (0-based, as standartized in the C language). +Here is defined, which one of the tracks is to go first (i.e. get number +0), either top or bottom, much like in the well known Overlay plugin. + +The last two controls apply to Blend Algebra only. + +Output track: +------------- + +Here is defined, into which track (top or bottom) the result will be placed, +much like in the Overlay plugin. Such an option is meaningless for Blend +Program: its programs produce no result, but modify the arguments directly. + +Hide input tracks, use output exclusively +----------------------------------------- + +If this checkbox is on (the default), frames of the tracks the plugin is +attached to, are cleared and then replaced by the function result. If the +checkbox is off, only the output track frame is replaced by the result, all +the other tracks are left unchanged. In comparison, the Overlay plugin has +no such option, its input tracks are always cleared as if this checkbox were +in the 'on' state. + +All the parameters described above are keyframable, including user functions +themselves. Namely, a plugin can have several functions attached in the +same time and switch between them while rendering. The color and alpha +channels of the substitution (key) color are interpolated between keyframes, +the other parameters are switched. + + User library, system library, and Cinelerra project directories + =============================================================== + +The user library directory is that defined by the environment variable +$CIN_USERLIB, or, if CIN_USERLIB is not defined, $HOME/.bcast5lib as a +fallback default. The functions for Blend Algebra reside there in +subdirectory dlfcn/ba, for Blend Program - in dlfcn/bp (here 'dlfcn' stands +for 'dynamic loaded function'). Having user functions in such a library, in +a single place, makes it convenient to reuse the same functions in different +projects. The 'Copy to userlib' button in the Attach... file selection +dialog is handy to save such functions in the user library for future use. + +The reason to place user library in the distinct directory $HOME/.bcast5lib +by default (and not in the common $HOME/.bcast5) is the following. There +exists a common workaround, if a newer version of Cinelerra does not start, +to delete $HOME/.bcast5 completely and start with a fresh one. Doing so, +all user functions, should they be saved in such a place, would be +permanently deleted. + +The system library is defined by the environment variable $CIN_DAT, the +Cinelerra installation path, and there under the same subdirectories +dlfcn/ba or dlfcn/bp. System library is meant for functions distributed +with Cinelerra. + +When a complete project is to be exported, or fed to a render farm, it can +be often necessary to place all the resources under the same directory where +the project .xml file resides. If some functions are used, which reside +elsewhere (for example, in a user library), they could not be found after +exporting the project to another computer. The 'Copy to project' button in +the Attach... file selection dialog is used to copy such functions to the +project directory in a convenient manner. + + Blend Algebra / Blend Program workflow + ====================================== + +As in any realtime plugin, the process_buffer() method in Blend Algebra / +Blend Program gets a set of frames from the tracks the plugin is attached +to. Then the following events take place. + +As in any other plugin, it is checked if the configuration (the parameters) +got changed. There is one parameter which requires special treatment, the +user function name. + +In order to prevent from resource consuming recompilation of the functions +on each new frame, the plugin maintains in memory cache of the successfully +compiled and attached functions. If at some keyframe the function name gets +changed, the plugin searches if this function is already known and cached. +Among other important function related objects, such as entry points, there +is a timestamp, when this function was last checked to be up to date. + +If the current function name is empty, it means a function is not used. +Nothing else has to be done, all tracks are fetched and passed further in +the processing pipeline unchanged. + +If the function is not empty and seen for the first time, or its timestamp +is older than the global timestamp, it is checked as follows. + +File lock is placed on the function source file, to prevent from concurrent +modification of object files in case of several simultaneous compilations. + +The compilation script BlendAlgebraCompile.pl (BlendProgramCompile.pl) is +started. The script checks if the resulting shared object file exists and +is newer than the source, and recompiles it, if not (just like the well +known `make' program). + +The plugin checks if the shared object timestamp became newer than the +timestamp of this function in cache (if any). If the cached version of the +function in memory is up to date, it stays there. If not, the outdated +function is detached from the plugin, the updated one is reattached, its +entry points are fetched and memorized in cache. The function's timestamp +in cache is set to the current time (as the function just has been checked). + +While recompilation and dynamic linking various things may go wrong. + +If the given function file does not exist, the program does nothing, as for +empty function. No error message is shown in this case, to prevent from +possible deadlocking situations. This case is not very probable because +usually the user will select functions via the Attach... dialog and clearly +see if the chosen function exists. + +If recompilation was unsuccessful (because of a syntax error), the error +message is shown. More detailed diagnostics from the compiler can be seen +in the terminal window in which Cinelerra was started. Although it would be +possible to fetch the compiler output and show it together with error +message, modern compilers, like gcc, bring more descriptive coloured +diagnostics, better than we can show in a Cinelerra dialog. + +If compilation succeeded, but dynamic linking did not, error message is +shown. In case of any error, the failed function is marked with the current +timestamp in cache, so that such error messages appear only once before +global timestamp gets updated. + +Updating global timestamp forces all cached functions to be checked for +recompilation at their first access. The global timestamp itself is updated +by the following events: changing function name, pressing Edit... or +Refresh button, exiting the Attach... dialog with the OK button. + +If currently active function is ensured to be up to date and correctly +attached, the plugin fetches video frames from all the affected tracks, with +the important parameters like frame width and height. Then the 'INIT' phase +of the function is executed (once for each frame). Here, several important +parameters are requested, which are defined by the function. They are: + +Working color space needed inside the function. If it is not the same as +the color space of the project, then color space conversions have to be +done. + +The required number of tracks the function works on. If less than the +required number of tracks is available, error message is shown and the +function is not executed. + +Whether the function supports parallelizing or not. If the function does +not claim parallelizing support, it will be executed sequentially +independently on the corresponding checkbox in the plugin GUI. + +After this preparation phase, the processing itself takes place. In case of +sequential flow, the following is done, for each frame pixel individually. + +For each input track, the corresponding pixel is splitted to color +components according to the actual color space of the project. All color +components are converted to float (type of the C language) in the ranges +[0.0 .. 1.0] for R, G, B, A, Y or [-0.5 .. +0.5] for U, V. If the project +color space has no alpha channel, the alpha component is set to 1.0. + +If the function requires other color space than the project uses, the +necessary conversions are performed. The key color components (selected in +the plugin GUI) are also converted to the function color space in the same +manner. + +For Blend Algebra, the values for output are preinitialized from that track +where the output is to go to. All the other tracks are cleared if the +corresponding checkbox in the plugin GUI says to do so. For Blend Program, +this step is skipped. + +The user function is called with the parameters: actual number of tracks, 4 +arrays for the 4 color components (dimensions are equal to number of +tracks), 4 key color components, current pixel coordinates x, y (upper left +frame corner is (0,0), lower right is (width-1,height-1), width, height, and +the existence of alpha channel. For Blend Algebra, placeholders for the +result, additionally. + +The user function returns. First of all, the color components of the +relevant pixels are clipped to bounds if the corresponding checkbox in the +plugin GUI is on. Relevant for Blend Program are pixels of all the tracks +(all tracks can be modified), for Blend Algebra the result only. + +After optional clipping, the color components are checked for being legal +finite floating point numbers. If any is NaN, the affected pixel is +replaced with substitution color. + +Then backconversion to the project color space is performed. + +If the project has no alpha channel, but the function returned something not +equal to 1.0, alpha channel is simulated as if an opaque black background +were used. + +If the project color space is not FLOAT, unconditional clipping followed by +8-bit transformation takes place. + +For Blend Algebra, the result is placed to the right output track. For +Blend Program, this step is skipped, as all tracks are modified in place. + +Then the loop is repeated for the next pixel in a row, next row in a frame, +next frame in the whole sequence... + +If the function is to run parallelized, the necessary number of threads is +created (as defined in Settings->Preferences->Performance, Project SMP +cpus). Although it might seem that running parallel on 1 cpu be the same as +running sequential, strictly speaking it is not the case. To run parallel +on 1 cpu, an extra processing thread is still started, while sequential +execution takes place inside the main plugin thread. This could induce some +subtle differences if the function uses static variables inside or something +else which is thread unsafe. + + Syntax of Blend Algebra / Blend Program functions + ================================================= + +Blend Algebra / Blend Program functions are written in C (not C++, for +simplicity), and with usage of a set of special cpp macros hiding from the +user all the Cinelerra internals. This approach allows to write functions +of moderate complexity with almost no background in C programming. All +macros defined for user functions are written in capital letters. + +A typical Blend Algebra function consists of the following logical blocks. + +------------------------------------------------------------------------ + + +BLEND_ALGEBRA_INIT + + + +BLEND_ALGEBRA_PROC + + + +BLEND_ALGEBRA_END +------------------------------------------------------------------------ + +The macro BLEND_ALGEBRA_STOP terminates execution of the INIT or PROC phase +immediately and returns to the calling plugin. + +The structure of a Blend Program function is the same, only the word +'ALGEBRA' in all the macros must be changed to 'PROGRAM', here and below. + +The following macros can be used in the INIT phase. + +COLORSPACE_RGB +COLORSPACE_YUV +COLORSPACE_HSV + +Declare the working color space inside the user function. If there is no +such declaration, the native color space of the project (RGB or YUV) will be +used. + +REQUIRE_TRACKS() + +Declares the minimum required number of tracks the function uses. If the +effect is attached to more tracks, it is OK. If there are less tracks, it +is an error, and the function is not executed. + +The absence of such declaration means that the function can process any +number of tracks (one or more). + +PARALLEL_SAFE + +This declaration means that it is safe to execute the function in parallel. +Without this statement function will be executed sequentially, independent +on the state of the parallelization checkbox in the plugin GUI. + +The following special variables (macros) can be used for queries. + +PARALLEL_REQUEST + +1 == parallelization requested in the GUI +0 == parallelization switched off + +TOTAL_TRACKS + +The actual number of tracks passed to the function. + +HAS_ALPHA + +1 == the project color space has alpha channel (transparency) + +WIDTH, HEIGHT + +The dimensions of processed frames, in numbers of pixels. + +The following variables (macros) can be used in the PROC phase. + +TOTAL_TRACKS, HAS_ALPHA, WIDTH, HEIGHT - can be used as well. + +R(i), G(i), B(i) +Y(i), U(i), V(i) +H(i), S(i), V(i) +A(i) + +Color (and alpha) components of pixel from i-th track. Tracks numbering is +0-based, as standartized for C arrays. Although it could be possible to +write macros for 1-based indexing, it does not look as a good idea as it +would lead to confusion with standard array definitions and regular C +for-loops. So, the first track has number 0, the last one - number +TOTAL_TRACKS-1. All the color components are floating point values of the C +type 'float'. + +Here the letters R, G, B, H, S, V, etc. are for readability. If the user +has declared COLORSPACE_RGB, and then writes something like H(i), it does +not mean that he should get the H-component of color autoconverted to the +HSV color space. Actually R, Y, H are mutually identical to the 1-st color +component, so are G, U, S to the 2-nd, and B, V to the 3-rd one. + +Do we need such a true conversion inside a user function? Can a function +need more than one color space simultaneously? I do not yet imagine such a +case. Should it come, we can consider adding the explicit color space +conversion possibility. + +KEY_R, KEY_G, KEY_B +KEY_Y, KEY_U, KEY_V +KEY_H, KEY_S, KEY_V +KEY_A + +Corresponding color components of the key (substitution) color, in the +working color space of the function, and the opacity slider. + +R_OUT, G_OUT, B_OUT +Y_OUT, U_OUT, V_OUT +H_OUT, S_OUT, V_OUT +A_OUT + +Color components for the result, for Blend Algebra only. Blend Programs +return no result, and do not have such definitions. + +PIX_X, PIX_Y + +Integer X and Y coordinates of the current pixel in its frame, in the ranges +of [0 .. WIDTH] and [0 .. HEIGHT], respectively. + +CLIP_RGB(i) +CLIP_YUV(i) +CLIP_HSV(i) +CLIP_RGBA(i) +CLIP_YUVA(i) +CLIP_HSVA(i) +CLIP_A(i) + +These macros clip color components of the i-th track to the bounds +appropriate in the respective color space. + +CLIP_RGB_ALL +CLIP_YUV_ALL +CLIP_HSV_ALL + +Clip all color components (including alpha) for all tracks. + +CLIP_RGB_OUT +CLIP_YUV_OUT +CLIP_HSV_OUT +CLIP_RGBA_OUT +CLIP_YUVA_OUT +CLIP_HSVA_OUT +CLIP_A_OUT + +Like clipping track color components, but for the result of a Blend Algebra +function. Not relevant for Blend Programs. + +Clipping is done according to the inherent bounds of the respective color +space, as follows: + +RGB: [0.0 .. 1.0] for R, G, B +YUV: [0.0 .. 1.0] for Y, [-0.5 .. +0.5] for U, V +HSV: [0.0 .. 360.0] for H, [0.0 .. 1.0] for S, V +Transparency: [0.0 .. 1.0] for Alpha + +'H' color channel of HSV is brought into bounds by repeated rotation around +360 degrees, all the others by simple clipping. + +ABS(x), SQR(x), MAX(x,y), MIN(x,y) - absolute value, square, max and min +values for floating point arguments. Can be used in any phase of a +function. + +TO_RAD(x), TO_DEG(x) - conversion from degrees to radians and vice versa. + +CLIP(x,y,z) +CLAMP(x,y,z) + +Both macros clip the 'x' argument to bounds between y and z. CLIP returns +value leaving x unchanged. CLAMP assigns that value to x. + +All the macros are defined in the text header file +$CIN_DAT/dlfcn/BlendAlgebraStart for Blend Algebra and the analogous header +BlendProgramStart for Blend Program, in the same dlfcn subdirectory under +Cinelerra installation directory. These headers are prepended to user +functions before compilation. The user with a basic C knowledge can easily +understand what happens in these headers. + +Of course, it is allowed to use any valid C statements inside user +functions. As they are linked with -lm, the standard C math library, and of +course with glibc, almost any mathematical or C library function can be +called. C-style comments can also be used, and are welcome. + + The compilation script + ====================== + +Compilation of Blend Algebra and Blend Program functions is carried out by +Perl script BlendAlgebraCompile.pl and BlendProgramCompile.pl, +correspondingly. Both scripts are distributed in the dlfcn subdirectory of +$CIN_DAT, the Cinelerra installation directory. Much like the famous +ContextManual.pl script of Context Help, the system script at the first call +is copied into $CIN_CONFIG ($HOME/.bcast5) where can be edited by the user +and adapted according to his needs. + +While a regular compilation, the script works in that directory where the +function source file resides. Firstly, the BlendAlgebraStart +(BlendProgramStart) header is prepended to the source to produce an +intermediate file with the '.c' suffix. This C source is compiled by the +system C compiler (gcc by default) and linked with -lm to produce the shared +object ready for dynamic loading (attaching to the plugin). + +Usually the script is executed by the respective Cinelerra plugin when a +user function is to be compiled. But the script can also be run by the user +from console explicitly. Execution can be controlled by options starting +with the '-' character, the first argument not starting with '-' being the +function name to compile. The following options are recognized. + +-compile don't check modification time, compile unconditionally +-cfile don't remove intermediate .c file +-opt add optimizing options to compiler command line +-debug add debugging options to compiler command line +-warn add warning options to compiler command line +-edit open function source in text editor +-verbose verbose execution +-noapi don't copy itself to $HOME/.bcast5 +-h, -help, -? print short help and current configuration + +In the beginning of the script some variables can be redefined according to +the user's needs: the C compiler executable, compiler options for +optimization or debugging, text editor executable. + + Environment variables influencing plugin configuration + ====================================================== + +The following environment variables are taken into account in various places +in Blend Algebra / Blend Program. + +$CIN_CC: C compiler executable (default: gcc) + +$CC: C compiler executable if $CIN_CC is not defined (default: gcc) + +$CIN_EDITOR: text editor (default: emacs) + +$CIN_DAT (set by Cinelerra binary): Cinelerra installation directory. The +Blend Algebra / Blend Program system library with scripts, headers, and +functions distributed with Cinelerra resides in the subdirectory +$CIN_DAT/dlfcn. + +$CIN_CONFIG (set by Cinelerra binary): user's config directory, usually +$HOME/.bcast5 + +$CIN_USERLIB: user's library (default: $HOME/.bcast5lib). User's functions +reside in the subdirectory $CIN_USERLIB/dlfcn. + + What comes in the distribution + ============================== + +In the distribution 30 Blend Algebra functions are provided for all the 30 +CinelerraGG overlay modi, according to the formula defined in CinelerraGG +manual. In principle, they are not needed in themselves: the built in +overlayer engine is OpenGL accelerated and runs faster. Nevertheless, these +functions can be handy as starting examples for users who may like to modify +formula in some way. Secondly, their behavior differs from that of the +standard overlayer in several aspects: + +Overlayer produces different results in RGB and YUV color spaces, Blend +Algebra yields identical results independently on color space of the +project. + +In RGB(A) FLOAT color space overlayer results can get out of bounds, and +then be rendered differently depending on the display driver used. In Blend +Algebra clipping, when switched on, can prevent from this undesirable +effect. + +Overlayer always clears its input frames. In Blend Algebra the user has a +choice, either to clear them, or to leave intact. + +Besides the 30 example overlay functions, we provide the ydiff simulator +function actually representing the complete ydiff application running inside +Cinelerra plugin. + +Two functions are provided in forms of Blend Programs: the chromakey and +background functions. They can also serve as nice starting points for +further user's experimentations. + +The usage of the provided functions is either self evident, or shortly +described in the comments in their source files. + +`make install' copies the functions into the Cinelerra's bin directory in +source (*.ba, *.bp) and binary (*.so) forms by `cp -a', to preserve file +modification times. Otherwise, if modification time of the function source +accidentally becomes newer than that of its binary, the plugin will +repeatedly try to recompile this function. And if it is installed +system-wide, so that the user has no permission to modify it, such +recompilations will fail. + + Assorted considerations + ======================= + +Caveats +------- + +User's functions can have bugs. By axiom, any program has at least one more +undetected bug, and there is proof that any program has infinite number of +undetected bugs. + +Most probable bugs in a user function can be illegal arithmetic such as +division by zero or logarithm of a negative number (FPE, floating +exception), and out of bounds indexation of arrays (usually leading to SEGV, +segmentation violation). + +Most modern processors don't generate FPE. Instead, they generate NaN as +the result of an illegal arithmetics. After calling user functions the +plugins test the results not to be NaN and replace them with the configured +substitution color if necessary. + +SEGV is more problematic. If the user has written in his function, let's +say, REQUIRE_TRACKS(2), and then accesses R(1000000), most probably +Cinelerra binary will crash. Although theoretically it could be possible to +trap SEGV via sigaction()/setjmp()/longjmp(), in Cinelerra it is +problematic. In a multithreaded application, which Cinelerra is, only one +signal handler for all its threads in the same time is allowed, and +Cinelerra has already its SEGV handler which we are not allowed to +overwrite. Thus, the user is responsible for his indexation bugs, where +most attention has to be paid, as usually, to the off-by-one errors, like +referencing elements as R(TOTAL_TRACKS) (the last legal element being +R(TOTAL_TRACKS-1)), or R(i) where i has been decremented to -1. + +The user is allowed to call any C function from the -lm and glibc libraries. +But some functions are not thread safe (which means, PARALLEL_SAFE macro +should not be used), and some others have undesired side effects. For +example, should the user write inside his function something like +exit(R(0));, the whole Cinelerra would immediately halt. The user is left +to imagine what would happen after the following expression, for example: + +R_OUT = R (system ("killall -9 Xorg")); + +Acceleration +------------ + +Blend Algebra / Blend Program functions are not accelerated. Hardware +acceleration would mean, the function algorithm is to be programmed as an +OpenGL shader. I think, if the user is sufficiently experienced to write in +the OpenGL shader language, it would be not so difficult for him to write a +complete Cinelerra plugin. + +Nevertheless, functions can be parallelized (using the load balancing engine +of Cinelerra), and can be compiled with optimization (switched on by +default). The default optimizing option (defined in BlendAlgebraCompile.pl +and BlendProgramCompile.pl) is -O2. One can redefine it to -O3 or -Ofast, +for example. However, it has to be noted that using -Ofast or -ffast-math +options can lead to ignorance of some IEEE rules for floating point math, +namely, some intrinsic tests on infinities or NaN can yield unpredicted +results. + +Debugging +--------- + +Although user's function can be compiled with debugging option such as -g or +-ggdb, debugging functions can be tricky. The programmer can set breakpoint +into the function only after its code has been loaded in memory by the +plugin, and set another breakpoint into plugin only after that plugin itself +has been attached to a track. Moreover, a function can get detached from +memory under some conditions, and then its breakpoints will be lost. + +Debugging printout inside the PROC phase, although possible, would seem too +verbose: the PROC phase would be called for full-HD footage 2073600 times +per frame! Here perhaps one could make use of PIX_X, PIX_Y coordinates at +some characteristic place in a frame where the problem shows up, like in an +example: + +if (PIX_X == 320 && PIX_Y == 200) printf ("%f %f %f\n", R(0), G(0), B(0)); + +Editing functions +----------------- + +Thus far, to edit user functions an external editor has to be used. +Although it would be possible to implement editing directly in Cinelerra via +some multiline scrollable text field, this could hardly present features +comparable to a dedicated text editor. I'd say, we should not bother with +it. + +Portability +----------- + +The current implementation should be rather portable. One prerequisite is a +working C compiler. That compiler which was used to build Cinelerra itself, +will work by definition. But other compilers perhaps are compatible as +well. I tested at least functions which were compiled with clang, but +attached to Cinelerra compiled with gcc, they worked. + +If the user has built Cinelerra from sources, he definitely has a working C +compiler. But if one has installed the binary distribution, then the +compiler clearly is a prerequisite. + +Will Blend Algebra / Blend Program work under Cinelerra in an AppImage form? +Perhaps they should if a C compiler is installed. Can somebody who is +familiar with AppImages test this? + +What about other architectures? It has to be tested. If some other +architecture is Unix-like, and is ELF based, the things should be portable. + +But under Windows it is not the case. Unlike Unix/Linux, Windows does not +have ELF shared objects, and its DLLs are not fully position independent. +There exists a definite probability of conflicts between virtual addresses +which can prevent some user's functions from dynamic load. But does a +version of Cinelerra exist for Windows at all? No idea so far... diff --git a/cinelerra-5.1/msg/txt b/cinelerra-5.1/msg/txt index 75135b07..f90f64a4 100644 --- a/cinelerra-5.1/msg/txt +++ b/cinelerra-5.1/msg/txt @@ -3,6 +3,10 @@ For usage help, refer to the following: https://cinelerra-gg.org/download/CinelerraGG_Manual.pdf http://g-raffa.eu/Cinelerra/HOWTO/basics.html . +2025 January/February changes of note: + BlendAlgebra and BlendProgram major blending enhancements + have been implemented and documented in the Manual. + Flac library has been updated from 1.4.3 to 1.5.0. 2024 November/December changes of note: Building with oneVPL now available using --with-onevpl. SVT-AV1 has been updated from 2.2.1 to 2.3.0. -- 2.26.2