What does DisplayFunction->Identity do to graphics functions?

Question

Does DisplayFunction->Identity do anything at all in Mathematica 8?

In the third edition of Programming in Mathematica, Roman Maeder gives the following explanation:

The option setting DisplayFunction->Identity causes the graphics functions Plot[], Plot3D[], ParametricPlot[], and so on to generate the graphics in the normal way, but not to render the images. We use it if we want to manipulate the graphics further. Afterwards, we can render the images with Show[graphics,DisplayFunction->$DisplayFunction].

He is referring to the following piece of code:

z = x + I y;
cz = {Re[z], Im[z]};
vlines = Table[ N[cz], {x, -Pi/2, Pi/2, Pi/12} ];
vg = ParametricPlot[ Evaluate[vlines], {y, -1, 1}, DisplayFunction -> Identity ][[1]]

SameQ tells me that even without DisplayFunction->Identity, I will still get the same result for vg. Is Maeder's precaution no longer necessary in Mathematica 8?

Answer 1

This option is not relevant since version 6 of Mathematica.

Before version 6, graphics did not display immediately after evauating the (inert) Graphics[] expression. They could be shown using the Show command (it was a side-effect of Show). (This is the reason why the function which today is used to combine graphics has such an unusual name---Show.)

So building graphics went like this:

g = Graphics[ ... ]

(* the output of this would be formatted simply as the string --Graphics-- *)

Show[g]

(* now the graphics was displayed *)

Show displayed the graphics by evaluating its display function. Plotting functions (such as Plot) called Show automatically.

In version 6, any Graphics object is formatted by the front end as the image it represents (instead of the placeholder --Graphics--). Running the DisplayFunction is no longer needed (at least when using the standard notebook interface). But the mechanism is still in place, and we can try it out:

g = Graphics[Circle[], DisplayFunction -> CreateDialog]

(* this is shown the usual way---remember, the front end formats
   any Graphics expression as the "image"/drawing it represents *)

Show[g]

(* now CreateDialog is evaluated and a window with the graphics pops up *)

With the default version 8 DisplayFunction, which is Identity, Show would have returned the original graphics, as applying Identity to something just returns it as it is.

I hope this explains the purpose of DisplayFunction.

---

Edit:

There are still a number of display mechanisms that use DisplayFunction. One is <<Version5`Graphics` mentioned by @Mr.Wizard. You can find some others by checking the files in $InstallationDirectory/SystemFiles/Kernel/Packages, and the readme file there. The available options depend on the operating system. On Windows, you can try for example, <<Terminal` and <<JavaGraphics` (try both when running the kernel in command line mode, and don't forget to use Show).

Answer 2

==== EDIT: Applications/Usability - after @Jens comment ====

@Jens is right in his comment that this could be useful - thanks for bringing it up. You can define a function just once and then automate its application via global

SetOptions[Plot, DisplayFunction-> myFunctiom]

Now let see how it works.

===============================================================

In addition to the useful answers given, to figure out how things work, you can do a little experimenting of your own. First produce some usual plot

p=Plot[Sin[4 x]/x, {x, -9, 9}, Filling -> 0]

And check its options which will reveal the default setting for DisplayFunction

Options[p]

{AspectRatio -> 1/GoldenRatio, Axes -> True, 
 AxesOrigin -> {0, 0}, DisplayFunction :> Identity, 
 PlotRange -> {{-9, 9}, {-0.868934, 0.863343}}, 
 PlotRangeClipping -> True, 
 PlotRangePadding -> {Scaled[0.02], Scaled[0.02]}}

Now try experimenting:

Plot[Sin[x], {x, -6.6, 6.6}, DisplayFunction -> MyTestFunction]

So you see it just wraps around. So you can now do things like

DensityPlot[Sin[x] Sin[y], {x, -4, 4}, {y, -3, 3}, 
 ColorFunction -> "SunsetColors", Frame -> False, 
 DisplayFunction -> (GraphicsGrid[ImagePartition[#, 20]] &)]

Which you of course could do just simply wrapping you custom function around your plot in the first place, unless you want to automate your actions as explained in the beginning of the post.

Answer 3

Graphics rendering was fundamentally changed in Mathematica version 6. Before that graphics output was treated specially, like a Print statement. Now output graphics are treated much the same as any other expression, and output can be suppressed with ; (CompoundExpression).

The documentation states:

Between Versions 5 and 6

The graphics functionality has significantly changed. For compatibility purposes, use <<Version5`Graphics` to restore graphics capabilities from Mathematica 5. To restore the Mathematica 6 graphics capabilities, use <<Version6`Graphics`.

Over 800 completely new built-in objects have been added, some of whose names may conflict with names already being used.

The output form of a Graphics or Graphics3D object is now the rendered graphic rather than an output such as -Graphics-.

$DisplayFunction is now set to Identity, so that no side effect happens by default when evaluating a graphic. To produce a side effect similar to Version 5 output, you can use the Print function to print the graphic.

So in fact DisplayFunction -> Identity is the default.

Answer 4

Actually, I know just one special case where DisplayFunction -> Identity is in fact still needed even with version 8:

As I mention in this answer, assume you have started JavaGraphics in a Kernel-only session to make plots. Now you decide you're done displaying plots and instead want to create only non-displayed plots for export. Then you have to do something like this session:

In[1]:= <<JavaGraphics`
 -- Java graphics initialized -- 
(* Make interactive plots... *)
In[3]:= p=Plot[x,{x,0,1}]  
Out[3]= -Graphics-
(* after some more plotting, I want to stop displaying and export only: *)
In[6]:= r=Plot[x,{x,0,1},DisplayFunction->Identity];
In[7]:= Export["r.pdf",r]
Out[7]= r.pdf

The last plot isn't displayed but can be exported. Note that the semicolon ; does not determine whether a plot is displayed or not in this Kernel session. I.e., I could add the semicolon to line In[3] but it would make no difference.