FIL 1.7.2 Development documentation

Congrats! Now you have FIL's sources but you can't figure it out by yorself. This development documentation will help you with basic operations on the FIL core and will help to understand it.

to contents >>

FIl is completely modular script with main core procedure, core modules and individual processes. FIL written on Scheme language, so it can handle only with function. For now FIL compatible with GIMP 2.6/2.7/2.8 branches at once. Main core function is fil-spe-core. This table shows all FIL procedures:

Function	Line number (1.7.2)	Description
Core space
fil-spe-core	393	This is main FIL function. It launched by user and launch other functions. Main task of this function is proper launching other functions.
fil-stage-handle	638	This function doing a great work. It build dynamic list of processes and deliver code fragments to core. Function unite register FIL stages in one universal method.
fil-source-handle	719	This function dealing with source layer. It can take active layer or extract it from visible.
fil-plugs-handle	789	This function deliver to user information about binary plugin integration and about it's state. Also this procedure will help user to deal with missing plugins.
fil-dep_warn-handle	826	This procedure using to warn user about processes or profiles which cann't work without some binary plugins. It this case process should call this procedure.
fil-spe-batch	930	Function which providing batch FIL execution. This is simple cycle which calling core function and save result.
Pre-stage
fil-pre-xps	1150	Exposure correction pre-process.
fil-pre-monocle	1174	Monocle pre-process.
fil-pre-vignette	1204	Vignette simulating pre-process.
fil-prefx-badblur	1287	Border blur pre-process.
Color stage
fil-clr-sov2	1308	"SOV2" color process.
fil-clr-monochrome	1363	"Monochrome" color process.
fil-clr-lomo	1408	"Lomo" сolor process.
fil-clr-duo	1444	"Doutone" color process.
fil-clr-vintage	1494	"Vintage" color process.
fil-clr-chrome	1566	"Photochrom" color process.
fil-clr-dram	1716	"Dram" color process.
Grain stage
fil-grn-adv_grain	1748	"Grain+" grain process.
fil-grnfx-sulfide	1806	"Sulfide" grain process.
fil-grnfx-dram	1909	"Dram Grain" grain process.

Input arguments for all functions are commented in source file (look around line number specified in table above). Of course the most interest part of FIL is core functions. As you see processes of FIL separated on three stages (pre-stage, color stage and grain stage). Color processes and grain processes are very simular to each other. Pre-processes is different. Pre-processes has their own option in сore arguments. Since FIL 1.6 color processes and grain processes were united in one interface. In core code it locate in different stages but all of them uses one execution interface. It was called "register stage". To deal with it register stages was desighned only one functiion: fil-stage-handle. This function providing dynamic process management in register stages. Main task of this function is make process management simplier. In FIL 1.0 developer has to manually add process code, insert "case" condition in the FIL core and insert list entry in script-fu registraition. Now it's in the past.

to contents >>

FIL has several classes of variables. Global variables, core arguments and local core variables.

Global varibles are defined for hole script. Its variables available from any function of the FIL. All global variables has prefix fk-* (fk-stages-list for example).

Core arguments are as function arguments for fil-spe-core. This variables available only in core function. All core arguments has prefix fm_* (fm_image for example).

Local core variables are core internal variables which defined by let operator within fil-spe-core function. This variables available only within let operator range. Local core variables has several groups:

System variables with image properties (has a fc_* prefix);
Local stages control variables for non-register stages (has a fl_* prefix);
Result variables recieved from stage handler (has a fx_* prefix);
Unifed stage I/O layer variable: fio_uni_layer;
Option indication string prefixes (has a fs_pref_* form);
Additional string variables (has a fs_*_str form);

to contents >>

Before you add your own process in FIL you have to prepare it first. Ussualy processes were ported in FIL from normal script. To port process you should remove all GIMP registration functions (like script-fu-register). After this you should change the code according to this rules:

process can use binary plugin procedures by using core permissions in fk-*-def variables;
if process can't work without some plugin then message should appear (via fil-dep_warn-handle);
process can call to binary plugin only in NON-INTERACTIVE mode;
processes shouldn't call other FIL processes from itself but it can call private additional procedures;
processes shouldn't change image dimensions or it's color depth;
procceses able to take some image option from FIL core by itself (variable class fc_*);
register stage should be defined by it's variable and should be included in fk-stages-list;
processes (except pre-proccesses) should be register in fk-clr-stage and fk-grain-stage variables;
processes should return final layer to core (if processes use many layers);
processes could have special launch options (for creating profiles);

This rules are necessery for FIL correct work. If process correspond to this rules then all will be fine.

to contents >>

GAL API currently is completely removed from FIL core code and processes. All components should use only GIMP 2.8 native procedures.

to contents >>

FIL 1.7.0 (and higher) allow integrate third-party binary plugins into processes. To achieve this goal FIL uses global variables. To integrate plugin you should place code like this in global variables area (line #371):

(define fk-plug-def (if (defined? 'some-plugin) TRUE FALSE))

where:
fk-plug-def is a global variable which display presense of the specified plugin;
'some-plugin plugin procedure name with apostrophe;

To use binary plugin in process you have to check its presense by using global core variable. For complete integration with FIL you also should place plugin entry into fk-plugs-list:

(list "plug_name" "plug_hompage" fk-plug-def)

where:
"plug_name" is a plugin name string;
"plug_hompage" is a string with plugin's homepage adress;
fk-plug-def is a global variable which display presense of the specified plugin;

This entry need for gathering information about missing plugins. Procedure fil-plugs-handle will generate report about missing and founded plugins by using such information.

Plugin integration shouldn't harm process and process shouldn't depend on plugin. In other words process should has secendary algorythm if plugin is missing. If you don't have secondary code or plugun result is unique then you should warn user about it by using fil-dep_warn-handle procedure.

Integration in process looks like this:

(if (= fk-plug-def TRUE)

	;Plugin launching
	(some-plugin arg1 arg2 arg3)
	
	;Display warning message
	(fil-dep_warn-handle dep_id)
)

where:
some-plugin arg1 arg2 arg3 call to plugin;
dep_id is a plugin number according to fk-plugs-list;
fk-plug-def is a global variable which display presense of the specified plugin;

If plugin is absent FIL may interrupt further execution (in batch mode).

to contents >>

This is simple. First of all you should copy-paste prepeared process code in main script. For registring FIL uses a global variables such as fk-stages-list (contain information of all stages). To add custom process you should to find proper stage. For color processes there is a fk-clr-stage variable list and fx-grain-stage for grain processes. This two variables are very simular and are part of fk-stages-list. Register list example for color stage (see fk-clr-stage in source):

(list "Process_name" BOOLEAN (quote (process_name arg1 arg2 arg3)))

where:
"Process_name" is desired process name (this string will be used for GUI list entry);
process_name arg1 arg2 arg3 are name of process function and its arguments (uses fil-spe-core variable space);
BOOLEAN is a boolean value. TRUE for returning layer from process. FALSE for keep it.

WARNING! To call process you should use fk-sep-image as image variable instead fm_image.

In FIL 1.7.0 there is many changes in register procedures. Manual assignment layer by set! is no more neccessary. Now register stage will extract boolean value from process registry entry and do the rest. And now FIL uses single layer for all stages: fio_uni_layer local core variable.

After proper register your process will appear in list of processes. Order of registring isn't matter, FIL will deal the rest.

to contents >>

This is a little bit diffucult. Code copy-paste isn't enough. You have to build block of code to launch pre-process. Example of block for pre-process:

(if (= fm_pre_process_toggle TRUE)
	(begin
		(pre-process arg1 arg2 arg3)
		(set! fs_res_str (string-append fs_res_str fs_pre_process_str))
	)
)

where:
fm_pre_process_toggle is core argument and GUI toggle to activate pre-process;
pre-process arg1 arg2 arg3 are pre-process function call with its arguments;
fs_pre_process_str is core string variable for option indication (ussually it is a process name);

WARNING! To call process you should use fk-sep-image as image variable instead fm_image.

This block of code must be in pre-stage core block. This is not end. After this you should to dublicate activation condition from your block to fl_pre_flag activating block (at line #489). Place to cond operator entry like this (according to example above):

((= fm_pre_process_toggle TRUE) (set! fl_pre_flag TRUE))

This step is necessery to independ pre-process execution. You also may use more complex launching conditions for pre-processes. This is last step. After this you may configure additional pre-process features using GUI.

to contents >>

Profils are the process entryes in GUI list which using one process but with different options for each profile. It is the same to presets. To create profile you should replace some options from process internal variables to it's arguments. After just copy-paste process entry in stage global variable and change arguments value as you wish. Better when profiles has regular string form. Like this: process_name: profile_name. You can use profiles only for register stages.

to contents >>

It is very difficult and dangerous operation. Firstly you should decide which stage it will be (register or not?). Register function controling only by simple GUI list and able to launch only one process at once. Non-register stage provide custom GUI control and able to launch all process at once. This is two dualistic treatments.

Anyway you should to edit fk-stages-list variable. Now it is like this:

(define fk-stages-list 
  (list 
    FALSE			;Pre-process stage marked as FALSE (not register stage);
    fk-clr-stage		;Color process stage;
    fk-grain-stage		;Grain process stage;
  )
)

This variable contain lists of all register stages. Non-register are marked as FALSE constant. Order of lists in fk-stages-list corresponds to stages order of execution. You shouldn't carelessly brake order of execution.

Add FALSE in fk-stages-list if your stage is non-register. If your stage is register then add name of list variable (also you should define a complitable list). For example:

(define fk-stages-list 
  (list 
    FALSE			;Pre-process stage marked as FALSE (not register stage);
    fk-clr-stage		;Color process stage;
    FALSE			;Mid-process stage marked as FALSE (not register stage);
    fk-grain-stage		;Grain process stage;
  )
)

WARINING! By adding new stage you will shift stage order. Those function which call fil-stage-handle by using ablolute stage number will return error. GUI list building procedure have to use absolute stage numbers. You should correct fil-stage-handle arguments in fil-controls variable (line #930). According to example above (stage numbers begun from zero):

SF-OPTION "Grain process" (fil-stage-handle TRUE 3 0)

Every time when you changing stage execution order you also have to manyally correct arguments in fil-controls. After this all will be fine. Anyway fil-stage-handle has code to error debuging.

to contents >>

;Stage initalization
(if (= fm_stg_flag TRUE)
	(begin

		;Recieved layer checking
		(if (null? fio_uni_layer)
			(set! fio_uni_layer (fil-source-handle fm_image fm_misc_visible))
		)

		;Process list initalization
		(set! fx_stg_list (fil-stage-handle FALSE fk-stage-counter fm_stg_id))
		(set! fs_stg_str (car fx_stg_list))
		(set! fio_return_flag (cadr fx_stg_list))
		(set! fx_stg_exp (caddr fx_stg_list))

		;Process execution
		(if (= fio_return_flag TRUE)
			(set! fio_uni_layer (eval fx_stg_exp))
			(eval fx_stg_exp)
		)
		

		;String modification
		(set! fs_res_str (string-append fs_res_str fs_pref_stg fs_stg_str " "))
		)
	)
)

where:
fm_stg_flag is a core argument which activate specified core stage (ussualy it is a GUI toggle);
fio_uni_layer is a local core variable for stage i/o single layer for all stages;
fio_return_flag is a local core variable for process return value;
fx_stg_list is a local core variable for list recieved from fil-stage-handle;
fs_pref_stg is a local core variable for stage string prefix (using as separator in option indication);
fs_stg_str is a local core variable for current process string mark (using in option indication);
fx_stg_exp is a local core variable for code quote recieved from fil-stage-handle;
(eval fx_stg_exp) is a operator to process execution;

This is tipycal register stage. Modifications of register stage is not recommended because it will affect on whole FIL.

to contents >>

Code block for non-register stages is complex (many conditions). Typical non-register stage has such structure:

;Stage activation section
(cond
	((process_condition_1) (set! fl_stg_flag TRUE))
	((process_condition_2) (set! fl_stg_flag TRUE))
	((process_condition_3) (set! fl_stg_flag TRUE))
)

;Stage initalization
(if (= fl_stg_flag TRUE)
	(begin
	
		;Recieved layer checking
		(if (null? fio_uni_layer)
			(set! fio_uni_layer (fil-source-handle fm_image fm_misc_visible))
		)
	
		;Process_1 launching
		(if (= process_condition_1 TRUE)
			(begin
				(process_1 arg1 arg2 arg3)
				(set! fs_res_str (string-append fs_res_str fs_process_1_str))
			)
		)
		
		;Process_2 launching
		(if (= process_condition_2 TRUE)
			(begin
				(process_2 arg1 arg2 arg3)
				(set! fs_res_str (string-append fs_res_str fs_process_2_str))
			)
		)
		
		;Process_3 launching
		(if (= process_condition_3 TRUE)
			(begin
				(process_3 arg1 arg2 arg3)
				(set! fs_res_str (string-append fs_res_str fs_process_3_str))
			)
		)
	)
)

where:
process_condition_1(2,3) are a launching conditions for processes in non-register stage;
fl_stg_flag is a local core variable for flag which will open the non-register stage to execution;
process_1(2,3) arg1 arg2 arg3 are calls to process functions and theirs arguments;
fs_process_1(2,3)_str are local core variables for processes string indentificators;
fio_uni_layer is a local core variable for single i/o layer for all stages;

It is typical non-register arhitecture. Of course you may modificate it as you wish.

to contents >>

Between two stages ther is special block of code. No matter is stage register or not. If you were added some stages then place between stages code like this:

;Stage counter correction
(set! fk-stage-counter (+ fk-stage-counter 1))

This code is necessery to call fil-stage-handle by using core counter variable (fk-stage-counter).

to contents >>

That is all. If you find some misstakes or you have question about FIL then let me know (see contact information below).

Best regards
Nepochatov Stanislav aka spoilt_exile

to contents >>

FIL at GIMP plugin registry
FIL at GitHub

to contents >>

email: spoilt.exile@gmail.com
jabberID: spoilt_exile@draugr.de