1RFX - a simple high level abstraction for guiding the creation of automatically generated parameter interfaces. 2 3The RFX (originally this stood for Rendered Effects) standard is designed to simplify the creation and customisation of 4auto-generated parameter interfaces, in particular the type of interface used by a host application to set the parameters 5for a variety of plugins. The protocol described is not directed specifically toward any particular graphical toolset, 6 rather it provides a higher level abstraction which may then be rendered using standard components of the toolset. 7 8 Furthermore, the design of the protocol is modular; the major components (parameters, parameter window, triggers) 9 are designed to work in harmony but each may also be used independently, providing flexibilty to the application 10 developer whilst minimising the need to duplicate code for vary classes of plugins. 11 12--------------------------------- 13 14Author: salsaman+lives@gmail.com 15Last edit date: 06 June 2020 16API Version: 1.8.4 GNU FDL 17 18Changes 191.0 First version salsaman@xs4all.nl 201.1 Added input channels 211.2 Added "<author>" section 221.3 Added "<define>" section 231.4 Added string support, made line delimiter fixed (\n) 241.5 Added note about LC_NUMERIC 25d1.6 Added string_list parameter type 261.7 Updates for compatibility with realtime effects 271.8 Add special multirect, deprecate multrect, and remove audiochannel. 28 29--- API Major / Minor Version frozen --- 30 31- Add "special|framedraw|multirect|"; add some hints about interpreting "special" keyword in "<layout>" 32- Add "special|framedraw|singlepoint|" 33- multirect -> multrect, fix description of it. 34- Add missing "label" field for string (documentation error) 35- Correct "language code" 36- Added "batch generator" flag bit + explanation of generators. 37- Describe how width and height are passed back to host. 38- Add "special|fileread" 39- Added note about differing input image types 40- Add "special|password" 41- Fix text errors, add note about "$fps" 42- Clarify max length for fileread special keyword. 43- tighten up wording a little bit 44- Correct description of "multirect", remove mention of "multrect" 45 461.8.1 47- Add "special|filewrite" 48- License amended to LGPL to allow its use in closed source components. 49 501.8.2 51- Add "special|scaledpoint" 52 531.8.3 54- in LiVES-perl, values of width and height now set in $width, $height rather than $nwidth, $nheight. 55 561.8.4 Add special|fontchooser 57 58- clarified the meaning of "min frames" 59 60 61 62TODO: - split into RFX layout and RFX plugin components (?) 63 64 65 66Note: 67This license documents a standard. The license of this document is the GNU FDL (GNU Free Documentation License) 68version 1.3 or higher. 69The reference implementations are released under the LGPL v3 or higher. 70 71See: http://www.gnu.org/copyleft/fdl.html 72https://www.gnu.org/licenses/lgpl-3.0.en.html 73 74 75 761. Introduction 77 78RFX is a system for generating parameter windows and plugins, e.g. rendered 79effects from scripts. It currently has features for: 80 81- defining parameters 82- sending layout hints to a GUI about how to present a parameter window 83- allowing triggers when the parameter window is initialised, and/or when any of the parameter values are altered 84 85An addendum to the generic RFX standard may be used to provide the following: 86- allowing definition of code for pre/loop/post processing (where loop may be applied a number of times determined by the 87 application) 88 89 90Note: The first 3 parts are generic for any type of plugin; 91the final part is application specific and not neccesary for general usage. 92 93 94The system described year has been in use succesfully in the LiVES application 95for over 10 years with only very minor changes needed (clarifications and a handful 96of "special" type additions). It has succesfully been employed for a wide range 97of plugin types: video effects, audio effects, video decoders, encoders 98 99 100 101 102---------------------------------------------------------------------- 103 104 105RFX layout is now intended to be a standalone component which can be used for passing parameter window descriptions 106between applications. 107 108The script itself is divided into sections. The only required sections are <define> and <name>; the latter is simply used to enable 109differentiation betweem scripts and may be autogenerated randomly if required. 110 111Other optional sections are: 112<params> - may be used to declare the number and type of parameters to be displayed as well as 113 some implementation details (min, max, default value for example) 114<param_window> - may be used customise the layout of auto generated graphical interfaces 115<language_code> - this section is optional but must be present if <onchange> is present, determines the 116 specific (computational) language use in that section 117<onchange> - an optional section which uses simple scripting to update the value, min, or max of paramters 118 depending on inital conditions or value changes of other parameters 119 120The <language_code> may also be used to define a scripting language to be used and permit plugins to be *generated* from 121an RFX script. In this case the remaining option sections <pre>. <loop>, and <post> may also be used to generate a more 122complete standalone unit which can the be run independently. This was the original intended purpose of RFX, however it 123proved convenient to use combinations of the other sections within pre-compiled plugins. 124 125The the below was written with the intention of describing the entire process of generating a plugin and defining its 126parameters and interface layout. 127 128In fact any of the sections may be used independently, and those parts of the description which refer to other 129script sections should be ignored. 130 131 132-------------------------------------------------------------------- 133 134 135 1362. RFX Scripts 137 138 139The following section describes a full RFX script, and the rules which must be 140implemented in order to comply with the RFX script version 1.8 141 142 143NOTE: for RFX, the shell variable LC_NUMERIC should be set to "C"; that implies the radix character for 144numeric values is "." 145 146 147Scripts 148------------ 149 150Scripts are the beginning point for all effects/tools/utilities in RFX. 151From the script, an interface and or plugin can be generated for a particular host 152application. The details of the plugin generation are left to the authors of 153the relevant host applications. RFX script files are abstracted in the sense 154that they are not tied to any particular widget set, or to any particular 155method of transferring data between host and plugin. 156 157The function of the plugin is to return the data in each section as requested by the host. If applicable, it 158should also execute the code in the relevant code sections <onchange>, <pre>, <post>, <loop>. 159One may think of a builder tool which 160takes a script and generates a plugin, which the host can then load and use. 161For example there is the build_lives_rfx_plugin tool for the LiVES video editor 162which can generate an executable Perl plugin from a full RFX script. 163 164The function of the host is to build an interface as defined by either the parameters, parameter_window sections, or by combining both. 165The host should then run this parameter window and marshall the parameters back to the plugin. 166 167Some RFX scripts may use only the parameter_window and the other mandatory sections. 168 169 170 171 172Here are the sections (some mandatory, some optional) which comprise an RFX 173script file. Each section in the script file is laid out as follows: 174 175<keyword> 176value1 177value2 178</keyword> 179 180some keyword sections are optional, these are indicated below as: 181<keyword> [optional] 182 183some keyword sections take a single data value, some take multiple data values 184Keywords which take multiple values are indicated thus: 185<keyword> [list] 186 187In the case of multiple values, each value should be terminated by a newline 188(\n) character. 189 190Within values, the delimiter is '|'. A trailing delimiter in a line is generally ignored, but can be added 191for readability (as in some of the examples below). 192 193Note: 194As of RFX version 1.4, the field delimiter is set in the <define> 195section. However, the default value is assumed below. 196 197The field delimiter must be a single (ASCII) character. It may not be \0 or \n. 198 199The sections marked [plugins only] are only used when the script is being used to *generate* a plugin. 200 201Here are the RFX sections: 202 203<define> 204 205<name> 206 207<version> [plugins only] 208 209<author> [plugins only] 210 211<description> [plugins only] 212 213<requires> [optional] [plugins only] [list] 214 215<params> [optional] [list] 216 217<param_window> [optional] [list] 218 219<properties> [plugins only] [optional] 220 221<language_code> 222 223<pre> [plugins only] [optional] [list] 224 225<loop> [plugins only] [optional] [list] 226 227<post> [plugins only] [optional] [list] 228 229<onchange> [optional] [list] 230 231The contents of each section are described below. Note that the sections may be in any order in the script, however it is 232more readable if the ordering below is adopted. 233 234 235=== HEADER SECTIONS === 236 237<define> 238 239This mandatory section contains the following entities: 240field delimiter 241RFX version 242 243E.g.: 244 245<define> 246|1.8.4 247</define> 248 249The first character following the newline after <define> is the delimiter. This is followed (without any intervening characters or 250 whitespace) by the lowest RFX version the script is compatible with 251We shall assume for the purposes of this description that the delimiter is the character '|' 252The format of the version is the standard dotted <major>.<minor>.<micro> 253 254NOTE: the following sections apply only when a plugin is to be generated from the script. 255The sections beginning with <params> are more relevant for pre-generated plugins. 256 257NOTE: in the following sctions, where "free text" is used, the format of the text is UTF8, unless specifically noted otherwise. 258 259 260<name> 261 262This section is mandatory for generated plugins, and contains a single entry with the name of the script. The name 263not contain spaces, newlines or the delimiter character (|). Each plugin name should be unique for that author. 264 265 266e.g. 267 268<name> 269blank_frames 270</name> 271 272 273 274 275<version> 276 277This is a mandatory section for generated; = a version string for a plugin. It should be an integer. 278This is NOT the same thing as the RFX version in the <define> section. 279 280e.g. 281 282<version> 2831 284</version> 285 286<author> 287 288This is a mandatory section for generating, an "author" string for a plugin. Tje format is free text, 289but it may not contain newline or the delimiter character. An optional second field may contain the author's URL. 290 291e.g. 292 293<author> 294somebody@somewhere.com|http://www.mysite.org| 295</author> 296 297 298 299<description> 300 301This section consists of a single entry with 4 fields, it is mandatory for generated plugins: 302 303menu text|action description|minimum frames|num_channels 304 305e.g. 306 307<description> 308Edge Detect|Edge detecting|1|1 309</description> 310 311minimum frames is defined as follows: 312a value of -1 indicates a plugin which does not deal with video at all 313This type of plugin is designated a 'utility', an example being the frame_calculator 314 315a value of 0 denotes a plugin that is "stateless", i.e each frame is processed in 316the exact same way, regardless of its order in the sequence 317 318a value of 1 indiocates that the plugin updates some internal variables 319for each frame in a sequence 320 321 a va;ue of 2 or higher 322 denotes a plugin which makes use of the pixel data from 323 prior or evren future frames" 324 325For generators a value of 0 for min frames indicates that all generated images 326 are identical copies of each other. 327 328 a value of 1 indicates that the output frames vary and 329 330 a value of 2 or higher 331 indicates a "batch" generetar which simply produces a number of frames without 332 providing anny indication as to its progress. 333 334 335 336 337num_channels indicates the number of input channels. (LiVES currently will only 338accept 0,1, or 2 input channels). 339 340 341IMPORTANT NOTE 342A value of -1 for minimum frames indicates that the plugin will not actually 343process frames. This is useful for plugins where only a parameter window is 344needed. In the case that minimum frames is -1, the host application should 345simply display the parameter window and allow the user to change the values, 346but no processing of frames should be performed. This is useful with trigger 347code for tools like calculators. 348 349 350 351 352<requires> [optional] [list] 353 354This section consists of a list of required binaries for the generated plugin to run. 355Each entry in the list should be separated by a newline. 356 357e.g. 358 359<requires> 360convert 361composite 362</requires> 363 364The host and/or plugin will check that the required binaries are present in the user's $PATH 365before attempting to process any frames. 366 367 368 369=== PARAMETER SECTIONS === 370 371 372<params> [optional] [list] 373 374This section contains a list of parameters the plugin would like to receive from the host. Each entry in the 375list should be separated by a newline. Each entry in the list contains a 376variable number of fields depending on the parameter Type. 377 378The name of each parameter should be unique within the plugin. 379 380 381The types which are defined at the time of the current version are: 382 383num 384bool 385colRGB24 386string 387string_list 388 389Each type is defined thus: 390 391num: this is a numeric value. The 'num' type is immediately followed by a 392decimal number indicating the number of decimal places. An integer value is 393therefore declared as 'num0', while a numerical value with 6 decimal places of 394accuracy is declared as 'num6'. 395 396The parameter format for a num is as follows: 397parameter_name|label|type|default|minimum|maximum|step_size/wrap| 398 399 400NOTE 401An underscore in the label text usually indicates that the following character is a 402mnemonic accelerator for the parameter. In case the host does not support 403mnemonic accelerators, underscores may be excluded from the label text by the host. 404The text itself should be in UTF-8 format. 405 406 407The step size is the amount that the value is adjusted by 408for example when the arrows are clicked on a spinbutton representing this parameter. 409 A negative step_size means that the parameter values should wrap (max to min and min to max). In this case 410 the actual step size is give by taking the positive value of the number. 411 412e.g. 413 414<params> 415rotate|_Rotate selection by|num0|360|-3600|3600| 416</params> 417 418The decimal separate is '.' As noted earlier, on Posix systems, LC_NUMERIC may be set to "C" to help ensure this. 419 420 421bool: this indicates a boolean parameter 422The format for this parameter type is: 423 424parameter_name|label|type|default|group| 425 426e.g. 427 428<params> 429shrink|_Shrink rotated window to fit frame size|bool|0|0| 430</params> 431 432The default should be constrained to the values 0 (FALSE) and 1 (TRUE). 433 434The group field is an optional integer. If it is non-zero then this indicates a radio button group. 435That is, for all boolean parameters in the 436plugin which have the same group, only one may take a value of 1 (TRUE). 437 438 439 440 441 442colRGB24: this indicates a 24 bit RGB value. The leftmost 8 bits correspond to 443red, the next 8 bits to green, and the rightmost 8 bits to blue. 444 445The format for this parameter type is: 446parameter_name|label|type|default_red|default_green|default_blue| 447 448e.g. 449<params> 450startcol|_Start colour|colRGB24|255|255|255| 451</params> 452 453 454 455 456string: this indicates a string parameter 457 458The format for this parameter type is: 459 460parameter_name|label|type|default|max_length_in_utf-8_chars| 461 462The default may not contain the field delimiter character, however it may contain newlines. The encoding used is UTF-8. 463 464 465max_length is measured in utf-8 characters. It is an optional field, and if omitted, 466the maximum string length for the "language_code" will be used whenedver applicable. 467e.g. 468 469<params> 470text|Enter some _text|string|The default value is "default".\nThis is line 2|1024| 471</params> 472 473 474 475string_list: this indicates a list of string parameters, from which exactly one entry may be selected 476The format for this parameter type is: 477 478parameter_name|label|type|default|first_string|second_string|... 479 480No string may contain the field delimiter character, but the strings may contain newlines. 481 482 483 484The default is an index into the list of strings. 0 means the first string, 1 means the second, etc. 485The value returned will be an integer. 486 487e.g. 488 489<params> 490method|Choose a _method|string_list|0|method1|method2|method3| 491</params> 492 493 494Because of the ambiguity with trailing field delimeters, the last string in the list may not be empty. 495Empty strings are however, allowed at all other positions in the list. 496 497There is no requirement that the value be with the bounds of list. The behaviour in this case is undefined 498The intention is, therefore that the value should equate to a valid position in the list. 499 500 501 502 503 504RFX Interface Section 505--------------------- 506 507 508 509<param_window> [optional] [list] 510 511This section is used to provide layout hints to the host about how to draw a 512parameter window for this effect/tool. 513 514The format is a list of layout hints separated by newlines. Each line in the 515list has a keyword followed by one or more subfields separated by "|" 516 517Two keywords are currently supported: 518 519layout 520special 521 522 523layout is hint to the host about how to present a parameter interface to a human 524user. It is abstracted from any particular widget set. 525 526It is up to the host how each layout line in this section is actually 527interpreted. The design is kept as simple as possible to allow for the actual 528visual appearance to be liberally interpreted. 529 530However, 531the suggested way to picture this is to imagine that each layout line 532describes a horizontal 533box, with the boxes arranged in order from top to bottom within an interface window. 534Any remaining parameters would then be appended below this, within the same window. 535 536Other interpetations may be used if so desired, or the hints may be ignored 537altogether. 538 539IT IS, HOWEVER, HIGHLY recommended that the "password" hint is acted upon since 540it may be desirable to obscure the text, keep it secure, etc. 541 542 543 544 545=== LAYOUT === 546 547The layout keyword may be followed by 0 or more fields which describe a layout row. 548the fields can be: 549 550px == position of parameter x on the screen. The first parameter is p0, the second is p1, etc. 551 552The mapping of numbering to parameters may be taken from the 553<parameter> section. 554 555or they may defined elsewhere. 556 557 558fill == fill with blank space. Multple "fill"s may be used sequentially, or the fill keyword may be immediately followed by an integer 559number, e.g fill4 would indicate 4 fills. The actual fill size is 560determined by the host. However for a visually pleasing effect it is recommended 561that the size is chosen so that parameters are aligned vertically in sequential rows. 562 563"label" == a label 564 565hseparator == horizontal line separator 566 567 568Example: 569 570<param_window> 571layout|p0|"This is a label"| 572layout|p5| 573layout|p1|fill|p2| 574layout|hseparator| 575layout|p3|fill| 576layout|p4|fill| 577</param_window> 578 579This can be interpreted as: 580layout row 0: parameter 0 followed by a label with text "This is a label" 581layout row 1: paramter 5 582layout row 2: paramter 1, blank space, parameter 2 583layout row 3: horizontal separator 584layout row 4: parameter 3, blank space 585layout row 5: parameter 4, blank space 586 587Blank space at the end would likely indicate that the parameter should be pushed to the start of the layout row, 588rather than expanding fill it all. 589 590 591=== SPECIAL === 592 593A second keyword which can be used in the param_window section is "special". 594This indicates to the host some information about the role of a parameter or 595set of parameters. The host may then use this information to better present that 596role to the user. 597 598"special" is then followed by the TYPE of the special widget, and for some types this must be followed by a SUBTYPE. The list of TYPES and SUBTYPES is deliberately kept 599small. 600 601After the type and subtype the indices of the "linked" parameters appear. The amount (or amounts) of linked parameters is determined 602by the special type and subtype as defined below. In some cases the linked parameters may take multiple values, 603then it is up to the developers to determine which if any subset of values are 604 "current" 605 i.e. represented in the user interface at any one time. 606 607 608Example: 609 610special|framedraw|rectdemask|1|2|3|4 611 612this line would provide a hint that a special role with TYPE framedraw, and SUBTYPE 613rectdemask (rectangular demask) may be linked to parameters 1, 2, 3, and 4 614Note it does not provide any POSITIONAL information regarding the link parameters. 615That role is reserved only for "layout" lines. 616 617In view of this fact, only the parameter numeration (starting from 0) 618is used here, as opposed to p0, p1, p2 etc used in the layout lines 619(thus the p prefix can be thought of as POSITION). 620 621It is up to developers exactly how they visually interpret the special keyword. 622It is however, STRONGLY recommended to use at most ONE of each special type per 623interface window, since not all hosts may support multiple instances of a type. 624 625Below are the suggested interpretations for each type / subtype. 626 627 628=== TYPES === 629 630 631Special type "framedraw" - allows user drawing on a preview frame to control some parameters and vice-versa. 632 633 Bear in mind that it is the host which is doing the drawing here. 634 635 If a link parameters have 0 decimal places, then the value may be assumed to be in pixels. 636 If more than 0 decimal places, the value is a ratio 637 where {0.0, 0,0} is the top left, {1.0,1.0} is the bottom right of the image, {1., 0.} is top right, etc. 638 639 Subtype "rectdemask" - >= 4 numeric parameters : demask (only show) a region on the preview frame, from 640 position p0[n],p1[n] to p2[n],p3[n] [p2, p3 are absolute coordinates] More denerally, denotes "region of interest" 641 within the frame. 642 643 Subtype "multirect" - >= 4 numeric parameters : draw a rectangle (outline) on preview frame, 644 offset p0[n]*out_channel0_width, p1[n]*out_channel0_height, 645 scaled by p2[n]*out_channel0_width, p3[n]*out_channel0_height 646 [p2, p3[ are relative values. 647 648 Subtype "singlepoint" - >= 2 numeric parameters : draw a "target" point (e.g. crosshair) on the frame, at offset 649 p0[n],p1[n] 650 651 Subtype "scaledpoint" - 3 numeric parameters : draw a "target" point (e.g. crosshair) on the frame at offset 652 {p0 / p2, p1 / p2}, i.e p2 acts as a scaling / zoom factor. Conversly, if the point is moved on the screen, p0 and p1 should 653 be altered by the (x, y) delta in screen pixels divided by p2. 654 655 656Special type "aspect" - 2 numeric parameters : p0 and p1 may be aspect ratio locked to the corresponding to some initial 657 width and height; host should provide a way to select/deselect this 658 659Special type "mergealign" – 2 parameters 660The mergealign special widget links together two num type parameters. 661It has two toggle states as well as a neutral state. 662Toggling it one way should set the first parameter to its minimum value and the second parameter 663to its maximum value. Toggling the other way will do the opposite, set the first parameter to its maximum, 664and the second parameter to its minimum. 665 666Special type "fileread" - 1 string parameter : the linked string parameter should point to a file to which the user has read permissions. 667In this case the maximum string length may be ignored by the host if would result in truncating longer filenames. 668 669Special type "filewrite" - 1 string parameter : the linked string parameter should point to a file to which the user has 670write / create permissions. In this case the maximum string length may be ignored as with fileread. 671The host may confirm with the user in the case that the file already exists as the existing file may be overwritten. 672 673Special type "password" - 1 string parameter : the host may hide/obscure the input to this string. IT IS RECOMMENDED NOT TO IGNORE THIS HINT, FOR SECURITY CONSIDERATIONS. 674 675Special type "fontchooser" - 1 string parameter, one numerical. The first parameter may be set to a font name, the second to a font (point) size. 676 677 678================================== end interface section ================================ 679 680 681 682 683 684 685<properties> [optional] 686 687this is a bitmap field (currently 32 bit) for rendered effects. Hexadecimal values are allowed. 688some bits are defined already 689 6900x0001 == slow (hint to host) 6910x0002 == may resize 6920x0004 == batch mode generator 693 [NB. this is equivalent to a min frames | channels setting of 2|0 (see above)] 694 695If the "may resize" bit is set, _all_ frames in the processing block may be 696resized to a new width and height. The host should take measures to determine the new width / height of the output using its 697standard discovery methods. 698 699 700A "batch mode" generator is a plugin with 0 in channels, and which generates all frames in a single pass (i.e. the loop code is only to be run once). 701 702 703 7040x8000 == reserved, may be ignored / set / reset. 7050x4000 == reserved, may be ignored / set / reset. 7060x2000 == reserved, may be ignored / set / reset. 7070x1000 == reserved, may be ignored / set / reset. 708 709If the value of properties is not defined, it is assumed to be 0x0000. 710 711 712 713e.g. 714<properties> 7150x0001 716</properties> 717 718 719 720 721<language_code> 722 723The language code indicates the scripting language for the <pre>, <loop>, 724<post> and <onchange> sections. This is a 32 bit unsigned integer. Hexadecimal values are allowed. 725 726Current values are: 727 7280xF0 == LiVES-perl 729 730 731 732 733<pre> [optional] [list] 734 735This section is for rendered effects and contains code which will be executed before the processing loop. 736 737e.g. (in LiVES-perl): 738 739<pre> 740#calculate the number of frames 741$length=$end-$start+1; 742</pre> 743 744 745For non-batch-mode generators using LiVES-perl, this section is mandatory, and you must set $end equal to the number of frames which will be generated, e.g.: 746 747<pre> 748$end=100; 749</pre> 750 751For batch mode or non-batch-mode generators, you can also set the frame rate for the clip (this is optional). In LiVES-perl, this is done by setting $fps (which can take a floating point value), e.g. 752 753<pre> 754$end=100; 755$fps=25.0; 756</pre> 757 758 759 760 761<loop> [list] 762 763IMPORTANT NOTE 764This section is mandatory for rendered effect plugins (optional for non-processing scripts - where min frames is set 765to -1, see above) 766 767This section contains code which will be executed for each frame in the 768processing block. 769 770e.g. (in LiVES-perl): 771 772<loop> 773#negate each frame 774system("$convert_command -negate $in $out"); 775</loop> 776 777 778The rules for processing are as follows: 779 780in each pass of the loop you should produce an output frame (possibly by using 781the input frame). For example, in LiVES-perl, the output frame is called $out. 782The output frames should be created in numerical from the start of the 783processing block to the end in numerical order with no gaps. The image type 784should not be changed, nor should the palette. Frames may be resized provided 785the script has the "may resize" property bit set. 786 787If no processing is to be done on a pass, then the input frame should be 788copied to the output frame. 789 790An exception to this is if the plugin has no in channels, and set the "batch generator" flag bit. In this case, the loop code will be run *only once*, and the generator should create an alpha-numeric sequence of image files. If the plugin is a generator, and this flag bit is not set, the plugin should generate frame $out, and it should be of the correct type (e.g. jpeg if $out ends in .jpg) and all frames must be of the same width and height. 791 792One further exception - if two or more input frames are to be merged into one output frame, the 793input frames may be of different types (for example, a png image and a jpeg image may be merged 794into a single png image). In this case, all input images should be converted to the first input 795image type before merging. The resulting output image should also be of the same type. 796 797 798 799If the plugin sets the may-resize bit, or is a non-batch-mode generator, the width and height of the frames should be 800passed back to the host. 801In LiVES-perl this is done by setting $width and $height to the width and height in pixels, respectively. 802(N.B. prior to 1.8.3 this was $nwidth and $nheight) 803 804 805Plugins with no in channels (generators) may also set $fps to inform the host of the framerate of the 806generated clip. 807 808 809 810 811<post> [optional] [list] 812 813This section is for rendered effects only, and contains code which should be executed after all frames in the 814block have been processed. 815 816e.g. (in LiVES-perl): 817 818<post> 819#clean up a temporary file 820unlink "blank.jpg"; 821</post> 822 823 824 825 826<onchange> [optional] [list] 827 828This section contains the triggers for changing parameters either when the 829parameter window is first created, or when a parameter is changed. For example 830 an init type trigger could set the maximum and minimum values for a parameter 831depending on the current frame width and height. 832 833The format is: 834 835event|code 836 837event can be either "init" or an integer representing a parameter. The first 838parameter is given the number 0, the second parameter 1, etc. 839There can be multiple lines of code for each type of change. Code for the same 840trigger type is executed in the order in which it appears in this section. The format of the code depends on the value of <language_code>. 841 842 843e.g. (in LiVES-perl): 844 845<onchange> 846init|$p0_min=-$width+1; $p0_max=$width-1; $p1_min=-$height+1; $p1_max=$height-1; 8470|if ($p0) {$p3=$p4*$p5;} elsif ($p1&&$p5>0.) {$p4=$p3/$p5;} 8480| elsif ($p4>0.) {$p5=$p3/$p4;} 849</onchange> 850 851 852 853 854Examples: 855 8561) setup window for openGL playback plugin: 857 858const char *get_init_rfx(void) { 859 return 860 "<define>\\n\ 861|1.7\\n\ 862</define>\\n\ 863<params> \\n\ 864mode|_Mode|string_list|0|Normal|Triangle|Rotating|Wobbler|Landscape|Insider|Cube|Turning|Tunnel|Particles|Dissolve\\n\ 865tfps|Max render _Framerate|num2|" SE(DEF_FPS_MAX) "|1.|200.\\n\ 866nbuf|Number of _texture buffers (ignored)|num0|" SE(DEF_NBUF) "|1|256\\n\ 867dbuf|Use _double buffering|bool|1|0\\n\ 868fsover|Over-ride _fullscreen setting (for debugging)|bool|0|0\\n\ 869</params> \\n\ 870"; 871} 872 873 8742) Setup window for a simple encoder: 875 876const char *get_init_rfx(void) { 877 return 878 "<define>\\n\ 879|1.8.1\\n\ 880</define>\\n\ 881<language_code>\\n\ 8820xF0\\n\ 883</language_code>\\n\ 884<params> \\n\ 885form|_Format|string_list|0|mp4/h264/aac|ogm/theora/vorbis||\\n\ 886\ 887mbitv|Max bitrate (_video)|num0|3000000|100000|1000000000|\\n\ 888\ 889achans|Audio _layout|string_list|1|mono|stereo||\\n\ 890arate|Audio _rate (Hz)|string_list|1|22050|44100|48000||\\n\ 891mbita|Max bitrate (_audio)|num0|320000|16000|10000000|\\n\ 892\ 893fname|_Output file|string|| \\n\ 894</params> \\n\ 895<param_window> \\n\ 896special|filewrite|5| \\n\ 897layout|p5|| \\n\ 898</param_window> \\n\ 899<onchange> \\n\ 900init|$p5 = (split(/\\./,$p5))[0]; if ($p0 == 0) {$p5 .= \".mp4\";} else {$p5 .= \".ogm\";} \\n\ 9010|$p5 = (split(/\\./,$p5))[0]; if ($p0 == 0) {$p5 .= \".mp4\";} else {$p5 .= \".ogm\";} \\n\ 902</onchange> \\n\ 903"; 904} 905 906 907 908 9093) "negate" rendered effect, complete plugin script: 910 911<define> 912|1.7 913</define> 914 915<name> 916negate 917</name> 918 919<version> 9201 921</version> 922 923<author> 924Salsaman| 925</author> 926 927<description> 928Negate|Negating|1|1| 929</description> 930 931<requires> 932convert 933</requires> 934 935<params> 936neg|_Negate|num0|1|1|10000| 937skip|_Skip|num0|0|0|10000| 938</params> 939 940<param_window> 941layout|p0|"frames, then "|p1|"frames"| 942</param_window> 943 944<properties> 9450x0000 946</properties> 947 948<language_code> 9490xF0 950</language_code> 951 952<pre> 953$to_do=$p0; 954</pre> 955 956<loop> 957if ($to_do<=0) { 958 if ($to_do<=-$p1) { 959 $to_do=$p0; 960 } 961 else { 962 #need continuous frames for preview 963 `cp $in $out`; 964 } 965} 966 967if ($to_do>0) { 968 system("$convert_command $img_prefix$in -negate $out_prefix$out"); 969} 970$to_do--; 971</loop> 972 973<post> 974</post> 975 976<onchange> 977init|$p1_max=$length-$p0; $p0_max=$length-$p1; 9780|$p1_max=$length-$p0; 979</onchange> 980
