Import plug-in modules are used to capture images from add-on hardware, such as scanners or video cameras, and put these images into new Photoshop document windows.
More...
Detailed Description
Import plug-in modules are used to capture images from add-on hardware, such as scanners or video cameras, and put these images into new Photoshop document windows.
Import modules can also be used to read images from unsupported file formats, although file format modules often are better suited for this purpose. File format modules are accessed directly from the Open command, while Import modules use the Import sub-menu.
Prior to Photoshop version 4.0 these modules were called Acquire modules. Most of the internal nomenclature and function calls reflect the old naming conventions, to stay compatible with previous versions.
The file type for format modules for Mac OS is 8BAM, the extension for Windows is .8BA.
Please also see Writing Import Plug-ins
Define Documentation
Allows the plug-in to display an about box for the Import Module.
For this selector, the host does not pass the standard parameter block into the plug-in main routine. Instead it passes an AboutRecord.
See About Boxes for more information.
Allows the plug-in to indicate to the host the mode, size and resolution of the image being returned, so it can allocate and initialize its data structures.
In the handler for this selector, the plug-in can update its parameters based on the passed scripting parameters, and show the user interface, if requested.
During this call, the plug-in module should set AcquireRecord::imageMode, AcquireRecord::imageSize or AcquireRecord::imageSize32, AcquireRecord::depth, AcquireRecord::planes, AcquireRecord::imageHRes and AcquireRecord::imageVRes. If an indexed color image is being returned, the plug-in should also set AcquireRecord::redLUT, AcquireRecord::greenLUT and AcquireRecord::blueLUT. If a duotone mode image is being returned, you should also set AcquireRecord::duotoneInfo.
The plug-in host can loop back to acquireSelectorStart after completing acquireSelectorFinish to begin importing another image for multi-image importing. See Multiple Import for more information.
Returns an area of the image to the plug-in host.
Photoshop continues to call this routine until it either returns an error, or the plug-in module sets the AcquireRecord::data field to NULL. For a discussion of using AdvanceStateProc in the handler for this selector, see Advance State and Import Modules.
The area of the image the plug-in returns is specified by AcquireRecord::theRect or AcquireRecord::theRect32, AcquireRecord::loPlane and AcquireRecord::hiPlane. If the resolution of the imported image is always going to be very small (for example, NTSC frame grabbers), the plug-in can simply set AcquireRecord::theRect or AcquireRecord::theRect32 to the entire image area. However, if you are working with large images, the plug-in must use the theRect or theRect32 field to return the image in several pieces.
There are no restrictions on how the pieces tile the image; horizontal and vertical strips are allowed as are a grid of tiles. Each piece should contain no more than AcquireRecord::maxData bytes, less the size of any large tables or scratch areas allocated by the plug-in. These restrictions don’t apply if the buffer for the image data was allocated using the Buffer or Handle suites.
The AcquireRecord::data field should point to the actual data being returned. The fields AcquireRecord::colBytes, AcquireRecord::rowBytes and AcquireRecord::planeBytes specify the organization of the data.
The data field contains a pointer to the data being returned. The plug-in can allocate a buffer for the data using malloc or through the Buffer Suite Callbacks.
The plug-in module is responsible for freeing this buffer in its acquireSelectorFinish handler.
- Note:
- Be careful processing user-cancel events during
acquireSelectorContinue. Normally your plug-in would be expecting another acquireSelectorContinue call. If the user cancels, the next call is acquireSelectorFinish, not acquireSelectorContinue!
Photoshop is very flexible in the format in which image data can be returned.
For example, to return just the red plane of an RGB color image, use the following parameter values:
Return red plane of RGB
| Parameter | Value |
| loPlane | 0 |
| hiPlane | 0 |
| colBytes | 1 |
| rowBytes | width of the area being returned |
| planeBytes | ignored, since loPlane=hiPlane |
If you wish to return the RGB data in interleaved form (RGBRGB...), use the following values:. Return RGB data in interleaved form
Return RGB values in interleaved form
| Parameter | Value |
| loPlane | 0 |
| hiPlane | 2 |
| colBytes | 3 |
| rowBytes | 3 * width of the area being returned |
| planeBytes | 1 |
Allows the plug-in to clean up after an image import.
This call is made if and only if the acquireSelectorStart routine returns without error, even if the acquireSelectorContinue routine returns an error. Most plug-ins at least need to free the buffer used to return the image data. If Photoshop detects Command-period in the Mac OS or Escape in Windows while processing the results of an acquireSelectorContinue call, it calls acquireSelectorFinish.
For scripting issues related to acquireSelectorFinish, see Scripting at importSelectorFinish
The plug-in host can loop back to acquireSelectorStart after completing acquireSelectorFinish to begin importing another image for multi-image importing. See Multiple Import for more information.
- Note:
- If acquireSelectorStart succeeds, then Photoshop guarantees that acquireSelectorFinish is called.
Allows a plug-in module to adjust the Photoshop memory allocation algorithm.
Photoshop sets AcquireRecord::maxData to the maximum number of bytes it can allocate to the plug-in. For Import modules to perform efficiently, you should reduce maxData to permit Photoshop to process the imported image in RAM. Please see Memory Management Strategies.
Allows the plug-in to do any final cleanup, and is typically used in the case where a plug-in module is acquiring multiple images during a single invocation.
If your plug-in is using finalization (the host set AcquireRecord::canFinalize and the plug-in set AcquireRecord::wantFinalize) then the host makes this call after all possible looping is complete.
If your plug-in is scripting-aware and the plug-in has changed any initial parameters, it should pass a complete descriptor back to the scripting system in the PIDescriptorParameters structure.
- Note:
- If acquireSelectorPrepare succeeds, i.e., the result value is zero, and
wantFinalize=TRUE, then Photoshop guarantees that acquireSelectorFinalize is called.
Typedef Documentation
This structure is passed to the plug-in module through the parameter block.
See Plug-in Entry Point for an explanation of how the host calls a plug-in.
