Guide to Writing Fuses for Resolve/Fusion Part 1

Intro

In Blackmagic Fusion or the Fusion Tab on Davinci Resolve, a number of tools are available for you to use. But if one is not available then there is an option to write your own. There’s actually a couple of options, but we’re going to concentrate on the simplest option of a scripted tool known as a “fuse”.

Fuses are written in Lua and can be added and used in the normal way in the Node graph. However, the concept comes from an old version of fusion – so it’s poorly documented and not easy for people to get into. Hence the idea of this guide. We’re going to break it down into the sections you need and give the options available.

Registering a Fuse

When Resolve/Fusion boots up it scans some folders for fuses. The easiest way to know what this folder is on your system is to look in the pathmap settings for “Fuses:” . e.g. in Resolve click on the fusion tab, go to Fusion -> Fusion Settings -> Path Map, click the line that says “Fuses:” in the first column, then click the little folder. In Fusion 9 go to File->Preferences->Global and Default Settings->PathMap, click the line that says “Fuses”” and the folder.

In here you need to place a file with the extension .fuse . Now when Resolve/Fusion boots up they will find ths file and process it. Except it doesn’t do anything!

Till now I’ve been saying “Resolve/Fusion”, but to make things quicker I’m going to say “Fusion” from now on. But I’m referring to both Fusion and the Fusion tab in Davinci Resolve. So why doesn’t our script do anything? It’s because when fusion boots up it finds it, and expects us to tell it what the script’s name is, a broad description of what it does, and a basic idea of its nature and how it works.

We do this by calling “FuRegisterClass” .  Basically:

FuRegisterClass(string name, enum type, table attributes)

Name is easy. Here we want to put a string that name’s our Fuse. This is basically a string. But you’ll soon learn with Fusion fuses that there are always rules! Here the rule is that it should be alphanumeric or an underscore and can’t start with a number. So if my idea is to develop a top secret fuse and call it “007” then I’m out of luck! We also can’t do the classic “Hello World” because there’s a space. So for the case of examples, from now on, we’ll assume we’re building a fuse called “CGain”. Now I’ve just named our example something fairly generic, I should point out that when you developing your own unique fuse you should make sure this name isn’t something another fuse is likely to use. That’s why I put the C in!

So we have a name, which was relatively painless. So the next thing we need to tell fusion is what type of fuse it is. And here’s your baptism by fire! There’s a number of options here, some of which I’m not entirely familiar with, and most of which aren’t terribly well documented. But luckily you’re almost always going to end up writing one of three types.

CT_Tool – is your go to valid. It just represents a generic tool.
CT_SourceTool – for a tool that doesn’t require an input image. Like a generator of some kind. Although, setting this doesn’t actually stop you from defining an image input! You set it to this if you want Source Controls to appear in the inspector (see the later paragraph on optional attributes where there are some specifically relevant if you set this type)
CT_Modifier – for writing a modifier. This is a tool that doesn’t appear in the node graph but can be used to modify properties on other nodes

But for reference the other known types are:

CT_ParticleTool – which I think is deprecated
CT_ViewLUTPlugin – I’m not sure…but I suspect this is likely deprecated in favour of DCTL

In our example, we’ll use CT_Tool .

Okay…that perhaps wasn’t a bad as I made it seem! It was less of a baptism by fire and more of an unpleasant tickling by dirty stream water. So please put on your fire safety gear because I’m going to introduce the attributes! Attributes come in two kinds – “Required” and “Optional”. Let’s start with the required ones because you’ll be putting them in every fuse you write:

REGS_Category – this is basically where your fuse will appear on the tools menu. You can put a full path here and any missing categories will be created. Path should be separated by escaped backslashes (i.e. \\). For example if I want it to appear on the tools menu under Genius\Fuses then I write “Genius\\Fuses”. I generally just put “Fuses” here so that people know that it is a fuse they’ve installed rather than an existing tool. But you should use here a category that you think is most convenient to the end user.

REGS_OpIconString – Sounds like it should point to an icon file right? Nope! This is an abbreviation string for the tool. Basically it’s a shortname. Normally I use something like fHW (for fuse Hello World). The documentation says it’s used for the “toolbar menu and the bins”, but it’s also used by people when searching for tools. So it helps if it’s short!

REGS_OpDescription – Is a short description of the tool. It’s apparently used to describe it in some places. I can’t honestly say I’ve noticed where and clearly that could change. But you have to put it in.

Now the optional ones:

REGS_Name – remember our actual tool name earlier couldn’t contain spaces? Well, we can give it a friendly name that can. This is optional, but you probably want to do it unless your name is one word I guess.

REGS_OpNoMask – You set this to true or false, this will determine if the tool shows a mask input on the node. If you don’t include it then it’s false by default.

REG_NoAutoProxy – Is basically an override for autoproxy mode if set to true

REG_NoBlendCtrls – Have you noticed the trend of everything being backwards in the Fusion programming world? It’s all “NoXYZ”. Basically if this is true then there’ll be no Blend slider. The default is false

REG_NoObjMatctrls – As for REG_NoBlendCtrls but for Matte Controls

REG_NoMotionBlurCtrls – I think you get the point!

REG_Source_GlobalCtrls – Nope…they’re gonna trick you. It’s not all backwards! If you want Source Controls, set this to true, otherwise it’s false. Resolve at least likes to crash if you try this and your type isn’t set to CT_SourceTool

REG_Source_SizeCtrls – If true then the standard width/height controls show. If false they don’t. Again type needs to be set to CT_SourceTool.

REG_Source_AspectCtrls – Same as the previous but for aspect controls.

REG_Source_DepthCtrls – Same again but for depth controls.

REG_TimeVariant – provides an indicator to the caching system that this fuse’s output can vary depending on the time of the request. i.e. if it is set to true then we are telling fusion that even if everything else stays the same, the output could still change on successive frames. Fusion caching seems to have advanced a lot, but it is still a good idea to set it.

REG_Unpredictable – setting to true basically says anything could happen! It’s a suggestion Fusion does not cache it. This is sometimes useful for testing/debugging. It’s probably not something for production.

REG_Fuse_NoEdit – By default in the inspector for your fuse a button will show that says “Edit” and will open the file in your text editor. This is often useful for development. Setting this to true hides the button. But note: end users can still edit the file in the file system.

REG_Fuse_NoReload – By default in the inspector there’s a reload button. This is really useful for development as if you make a code change you either need to restart fusion or click this button before it knows about the changes. So the button is easier! If you don’t want end users seeing it or you really like seeing the fusion loading screen, you can set this to true!

REG_Fuse_TilePic – This is apparently a Fusepic table with a description and string that contain an icon for the tool.

REGS_Company – Your company name

REGS_URL – General URL

REGS_HelpTopic – Where to get help! (seems to generally be a url)

REGID_DataType – Used in modifier fuses to specify the type of data it outputs. (Generally one of Number, Point, Text)

REGID_InputDataType – Used in modifier fuses to specify the type of data it can modify (Generally one of Number, Point, Text)

REG_NoPreCalcProcess – true is meant to indicate that fusion should not try to call PreCalcProcess in a script but use Process instead (more on this later!). But generally fusion does this anyway.

There’s a handy hint here. Take a look at what comes after the REG in each string. If it’s just an underscore then the value is always true/false. If it is the letter S then the value going in there is always a string. If it’s ID then it’s always a type (that you also write as a string, like “Number”). Phew. Got it? We need to decide all this before we can write our first line of code! So let’s keep it simple and just use the required ones – here’s the first line of our HelloWorld fuse:

FuRegisterClass(“CGain”, CT_Tool, {
     REGS_Category = “Fuses”,
     REGS_OpIconString = ‘fCG’,
     REGS_OpDescription = “CGain Tool”,
})

If you put that in your fuse file and restart fusion then under the tools menu you’ll see our Hello World tool listed!

Carry on with Part 2

Leave a Reply