This node can be used to emulate depth of field using a postprocessing method. It can also be used to blur the image in other ways, not necessarily based on 'depth' by connecting something other than a zbuffer. More on that later.
When in the composit node window, the node can be found in the Blender 'Add' menu under Filters -> Defocus. The node requires two inputs, an image and a zbuffer, the latter does not need to be an actual zbuffer, but can also be another (grayscale) image or a single value input like for instance a time node.
The node uses the actual camera data in your scene. To set the point of focus, the camera now has a 'DoFDist'
parameter, which might look familiar if you have worked with yafray before. It is the same parameter, but now also used for Blender itself. It can be set in the main Camera edit panel, the button is right below the Lens value button.
To make the focal point visible, enable the camera 'Limits' option, the focal point is then visible as a yellow cross along the view direction of the camera.
The buttons from top to bottom:
Bokeh Type menu, here you can set the number of iris blades of the virtual camera's diaphragm. It can be set to emulate a perfect disk or it can be set to have 3 (Triangle), 4 (Square), 5 (Pentagon), 6 (Hexagon), 7 (Heptagon) or 8 blades (Octagon). The reason it does not go any higher than 8 is that from that point on the result tends to be indistinguishable from a disk shape anyway.
'Rotate, this button is not visible if the 'Bokeh type' is a disk. It can be used to add an additional rotation offset to the bokeh shape. The value is the angle in degrees.
Gamma Correct, is exactly the same as the 'gamma' option in Blender's general blur node. It can be useful to further brighten out of focus parts in the image, accentuating the bokeh effect.
fStop, this is the most important parameter to control the amount of focal blur. The default value 128 is assumed to be infinity, everything in perfect focus. Half the value will double the amount of blur. This is button is not available if 'No zbuffer' is enabled.
Maxblur, can be used to limit the amount of blur of the most out of focus parts of the image. The value is the maximum blur radius allowed. This can be useful since the actual blur process can sometimes be very slow, the more blur, the slower it gets. So setting this value can help bring down processing times, like for instance when the world background is visible, which in general tends to be the point of maximum blur (not always true, objects very close to the lens might be blurred even more). The default value of 0 means there is no limit to the maximum blur amount.
BThreshhold. The defocus node is not perfect, artifacts may occur. One such example is on in-focus objects on a blurred background, which has a tendency to bleed into the edges of the sharp object. Worst case scenario is an object in focus against the very distant world background, the differences in distance are very large and the result can look quite bad. The node tries to prevent this from occurring by testing that the blur difference between pixels is not too large, the value set here controls how large that blur difference may be to consider it 'safe'. This is all probably quite confusing, and fortunately, in general, there is no need to change the default setting of 1. Only try changing it if you experience problems around any in-focus object.
Preview. As already mentioned, processing can take a long time. So to help make editing parameters somewhat 'interactive', there is a preview mode which you can enable with this button. Preview mode will render the result using a limited amount of (quasi)random samples, which is a *lot* faster than the 'perfect' mode used otherwise. The sampling mode also tends to look like something a typical raytracer like yafray might produce, grainy, noisy pictures (though the more samples you use, the less noisy the result). This option is on by default, play around with the other parameters until you are happy with the results, only then disable the preview mode for the final render.
Besides for preview, it may possibly have it's artistic uses too...
Samples, only visible when 'Preview' is set. Sets the amount of samples to use to sample the image. The higher, the smoother the image, but also the longer the processing time. For preview, the default of 16 samples should be sufficient and is also the fastest.
No zbuffer, sometimes you might want to have more control to blur the image, for instance only blur one object while leaving everything else alone, or the other way around, or you want to blur the whole image uniformly all at once.
The node therefore allows you to use something other than an actual zbuffer as the 'Z' input. For instance, you could connect an image node and use a grayscale image where the color designates how much to blur the image at that point, where white is maximum blur and black is no blur. Or you could use a time node to uniformly blur the image, where the time value controls the maximum blur for that frame. It may also be used for a possibly slightly better DoF blur as well, by using a fake depth shaded image instead of a zbuffer. (A typical method to create the fake depth shaded image is by using a linear blend texture for all objects in the scene or by using the 'fog/mist' fake depth shading method). This also has the advantage that the fake depth image can have anti-aliasing which is not possible with a real zbuffer.
'No zbuffer' will be enabled automatically whenever you connect a node that is not image based (eg. time node/value node/etc)
Zscale, only visible when 'No zbuffer' enabled. When 'No zbuffer' is used, the input is used directly to control the blur radius. And since usually, a texture is only in the range 0 to 1, it's range is too narrow to control the blur properly. This parameter can be used to expand the range of the input, or for that matter, narrow it as well, by setting it to a value less than one. So for 'No zbuffer', this parameter therefore then becomes the main blur control, similar to 'fStop' when you *do* use a zbuffer.
To summarize, in general, use preview mode, change parameters to your liking, only then disable preview mode for the final render. For minimum artifacts, try to setup your scene such that differences in distances between two objects that may visibly overlap at some point are not too large. Keep in mind that this is not 'real' DoF, only a postprocessing simulation. Some things cannot be done which would be no problem for real DoF at all. A typical example is a scene with some object very close to the camera, and the camera focusing on some point far behind it. In the real world, using shallow depth of field, it is not impossible for nearby objects to become completely invisible, in effect allowing the camera to see 'behind' it. This is simply not possible to do with the current postprocessing method in a single pass.
If you really want or need to emulate such an effect, the only way to do this is to split up your scene into nearby and far object(s), rendering in two passes, then postprocess each separately and combine the results.
A final word of warning, since there is no way to detect if an actual zbuffer is connected to the node, be VERY careful with the 'No zbuffer' switch, if the Zscale value happens to be large, and you forget to set it back to some low value, the values may suddenly be interpreted as huge blur radius values that will cause processing times to explode and there is at this point no way to stop the process until it has finished, unless you 'kill' it... You have been warned...
(Note from Ton; I'll add ESC checking in nodes soon!)