Sections on this Page
In most cases, the first action a plug-in takes is to negotiate with Photoshop for memory. Other plug-in hosts may not support the same memory options.
Negotiating Space with Photoshop
The negotiation begins, in most plug-ins, when Photoshop sets the maxData field of the pluginParamBlock to indicate the maximum number of bytes it can to free up. The plug-in then has the option of reducing this number. Reserving memory by reducing maxData can speed up most plug-in operations. Requesting the maximum amount of memory for the plug-in requires Photoshop to move all current image data out of of RAM and into its virtual memory file. This allows the plug-in to run from RAM as much as possible.
For Filter modules, which use maxSpace and bufferSpace to negotiate with Photoshop for memory, the maxSpace field indicates the maximum number of bytes of information the plug-in can expect to access at once (input area size + output area size + mask area size + bufferSpace). The bufferSpace field allows the plug-in to specify how much buffer space it needs. Photoshop then tries to free up the requested amount of space.
If your plug-in’s memory requirements are small — if it can process the image data in pieces, or if the image size is small — only reduce maxData to those specific requirements, or only request that amount in bufferSpace. This permits many plug-in operations to be performed entirely in RAM with a minimum of swapping. In many cases, your plug-in only needs a small amount of memory, but will operate faster if given more. Experiment to find a suitable balance.
One strategy is to divide maxData 2, thus allocating half the memory to Photoshop and half to the plug-in. Another good strategy is to reduce maxData to zero, and then use the Buffer Suite Callbacks and Handle Suite Callbacks to allocate memory as needed. Often, this is most efficient for Photoshop, but requires additional programming.
If performance is a concern, you may want to perform quantitative tests of your plug-in module to compare different memory strategies.
maxSpace vs. bufferSpace on Mac OS
Photoshop has a couple different mechanisms for reserving memory. There are also mechanisms for reporting available memory. Together, they allow you to calculate what sort of processing parameters you will need to use, such as chunk sizes, etc. This section is designed to detail two specific fields that indicate available space: maxSpace and bufferSpace, from the Filter parameter block.
The amount of free space available in the Mac OS heap is returned in maxSpace. Photoshop uses its own linear bank code when the available memory goes over a threshold, generally around 32 mb. This is done because the Mac OS Memory manager gets very inefficient with large heaps.
Photoshop sets aside an area of memory, called the linear bank. The Mac OS sets aside an area of memory for the application, called the heap space. BufferSpaceProc() in the Buffer suite, and FilterRecord::bufferSpace return the amount of space available in the linear bank, or the heap space if the linear bank is not present. This memory is available via the Buffer suite. bufferSpace and maxSpace will be about the same up to 32 mb (they both reserve different amounts of padding) and then maxSpace will step back. bufferSpace will also step back, but grow as memory is available.
Neither maxSpace nor bufferSpace guarantee continguous space.
Photoshop memory and maxData/maxSpace
| Photoshop Memory | maxData/maxSpace |
| 1 mb | 4 mb |
| 16 mb | 6 mb |
| 26 mb | 14 mb |
| 31 mb | 19 mb |
| 32 mb+ | 9 mb |
Using Buffer and Handle Suites
Buffer Suite
The Buffer Suite Callbacks provides a mechanism for a plug-in to allocate and dispose of memory from the pool of Photoshop memory. This mechanism allows for the most optimal way for Photoshop and the plug-in to share memory, and allows you to tune the memory use of your plug-in to optimize performance.
Previous versions of the plug-in specification provide a simple mechanism for interacting with the Photoshop virtual memory system by letting a plug-in specify a certain amount of memory which the host should reserve for the plug-in. This communication is done through the maxData or bufferSpace member of the pluginParamBlock.
This approach has two problems. First, the memory is reserved throughout the execution of the plug-in. Second, the plug-in may still run up against limitations imposed by the host. For example, Photoshop 2.5 will, in large memory configurations, allocate most of memory at startup via a NewPtr call, and this memory will never be available to the plug-in other than through the Buffer suite. Under Windows, the Photoshop memory scheme is designed so that it allocates just enough memory to prevent Windows’ virtual memory manager from kicking in.
If a plug-in module allocates a lot of memory using GlobalAlloc (Windows) or NewPtr (Mac OS), this scheme will be defeated and Photoshop will begin double-swapping, thereby degrading performance. Using the Buffer suite, a plug-in can avoid some of the memory accounting. This simplifies the prepare phase for Acquire, Filter, and Format plug-ins.
For most types of plug-ins, buffer allocations can be delayed until they are actually needed. Unfortunately, Export modules must track the buffer for the data requested from the host even though the host allocates the buffer. This means that the Buffer suite routines do not provide much help for Export modules.
Handle Suite
The use of the Handle structure throughout the API poses a problem under Windows, where a direct equivalent does not exist. To facilitate Windows plug-ins, Photoshop implements a handle model, through the Handle Suite Callbacks that is very similar to handles under the Mac OS.
In general, the Buffer suite routines are more effective for memory allocation than the Handle suite. The Buffer suite may have access to memory unavailable to the Handle suite. You should use the Handle suite, however, if the data you are managing is a Mac OS handle.
Although you can allocate handles directly using the Mac OS Toolbox, these callbacks are recommended, instead. When you use these callbacks, Photoshop accounts for these handles in its virtual memory space calculations.
