Function

Summary

Ensures GDI+ is present and running, or shuts it down. Needed only when writing FLI graphics code on Windows.

Package

graphics-ports

Signature

ensure-gdiplus &key event-func force shutdown => result

Arguments

event-func

A function, or nil.

force

A boolean.

shutdown

A boolean.

Values

result

A boolean.

Description

The function ensure-gdiplus checks that the GDI+ module gdiplus.dll is loaded and that GdiplusStartup has been called, or shuts down GDI+.

Most users will not need to call ensure-gdiplus. This is because when LispWorks itself uses GDI+, for instance via read-external-image, it calls ensure-gdiplus automatically, and never shuts GDI+ down.

However, if your code uses GDI+ directly (by calling it through the Foreign Language Interface), then you should call ensure-gdiplus instead of using GdiplusStartup directly. Then, LispWorks will know that GDI+ has already started. This is the only circumstance in which you need to call ensure-gdiplus.

Note: ensure-gdiplus is implemented only in LispWorks for Windows.

If shutdown is nil, ensure-gdiplus ensures GDI+ is started, by the following steps:

1. Load the GDI+ module gdiplus.dll, if it is not already loaded.
2. If
   a) GDI+ was already started by a previous call to ensure-gdiplus, and
   b) force is nil, and
   c) event-func was either not passed or is cl:eq to the value that was passed for point a)

then ensure-gdiplus simply returns nil.

3. If GDI+ was already started, shut it down.
4. Start GDI+, and return the result of GdiplusStartup. This is 0 for success. For he meaning of other values, see the documentation of gpStatus in the MSDN.

If shutdown is true, then if GDI+ was started ensure-gdiplus shuts it down, and returns t, otherwise ensure-gdiplus returns nil. The default value of shutdown is nil.

The default value of both event-func and force is nil.

See also

read-external-image