Photogenics and the Amiga Environment:
Getting images in and out of Photogenics
Internal image management, gruntbatching and main convolutions:
The main drawing tools, applying effects to images
Getting user input, script Interfacing
Working with the paint layer and alpha channels
Intelligent scripting and sanitychecking:
Advanced long-distance batch-prcessing, stealth mode
Highly advanced direct vodoo image control. Coders only.
Format: ABOUT
Function: The About requester is displayed and script execution paused until the requester is closed.
Example:
/* show about requester */ address PHOTOGENICS.1 ABOUT
Format: ADDSPACE buffer top left bottom right
Function: Adds more space to the outside of the image (borders).
Parameters:
Format: ADDTEXT buffer x y justify text
Function: Sets the text used in ADDTEXT to the selected font parameters.
Parameters:
Format: ADDTEXTDO buffer
Function: Applies the AddText operation previously set up with ADDTEXTFONT and ADDTEXT
Parameters: buffer - Pointer to the buffer. Must be the same as used in ADDTEXT.
Format: ADDTEXTFONT fontname fontsize fontstyle
Function: Sets the font used in ADDTEXT to the selected font parameters.
Parameters:
Format: ALPHA
Function: Return a pointer to the current alpha image, if one is selected within Photogenics.
Function returns: 'buffer' is a unique pointer to the alpha image
buffer. This result is used as a lock on the image for all further
operations. rc = 0 on success, 1 if there was no alpha image.
Format: ALPHATOPAINT buffer
Function: The Alpha channel, if one is selected, is moved into the paintlayer for the currently selected image (it is converted to greyscale).
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO, NEW, etc.
Format: result ASKBOOLEAN title prompt gadget1 gadget2
Function: A requester is displayed.
Parameters:
Function returns: result - a string containing the resultant number.
Format: result ASKDRAWER title drawer
Function: A directory requester is displayed and a directory requested.
Parameters:
Format: result ASKFILE title drawer
Function: A file requester is displayed and a filename requested.
Parameters:
Format: result ASKNUMBER title prompt min max
Function: A number requester is displayed.
Parameters:
Format: result ASKSAVEFILE title drawer
Function: A file requester (of the black-background Save variety) is displayed and a filename requested.
Parameters:
Format: result ASKSIZE title def_x def_y
Function: An Image dimensions requester (like the one used for New Image) is displayed.
Parameters:
Format: result ASKSTRING title prompt
Function: A string requester is displayed.
Parameters:
Format: result ASKTWONUMBERS title prompt min max prompt2 min2 max2
Function: A number requester is displayed.
Parameters:
Format: BRUSH brushname
Function: The brush is selected as the brush for further painting operations.
Parameters: brushname - the name of the brush, in quotes.
Example:
/* Set brush to AirBrush. */ address PHOTOGENICS.1 BRUSH "AirBrush"
Format: BRUSHSIZE size
Function: The brush is resized to the selected size
Parameters: size - the requested size, in pixels.
Format: BUFFER
Function: If a buffer is selected inside Photogenics, the buffer number is returned.
Function returns: 'buffer' is a unique pointer to the image
buffer. This result is used as a pointer to the image for all further
operations. rc = 0 on success, 1 if there was any problems preventing the
image loading.
Note: This is useful if you wish to write an effect macro to apply to the current image within Photogenics.
Example:
/* fill current buffer */ option results address PHOTOGENICS.1 BUFFER FILLIMAGE result
Format: CLEAR buffer r g b
Function: Clear the image buffer to the RGB value supplied.
Parameters:
Format: CLEARPAINT buffer
Function: Clears the paintlayer attached to the buffer.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Format: CLONE buffer
Function: Clones a photogenics image buffer. A new buffer pointer is returned.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Function returns: A new buffer pointer for the cloned image.
Notes: The name of the cloned image is automatically created using the same algorithmn that Workbench uses for copies of files. (filename, Copy of Filename, Copy 2 of Filename, etc.)
Example:
/* free the current buffer */ options results address PHOTOGENICS.1 BUFFER CLOSE result
Limitations: You cannot currently clone virtual images.
Format: CLOSE buffer
Function: Close a Photogenics image buffer, freeing its memory and losing any unsaved changes.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Example:
/* free the current buffer */ options results address PHOTOGENICS.1 BUFFER CLOSE result
Format: CLOSEPROGRESS
Function: Closes the Progress meter.
Notes:It is absolutely imperative that you always
CLOSEPROGRESS before ending a script where you have called OPENPROGRESS.
Format: COLOUR buffer RGB r g b
Function: Set the RGB values for the current paint colour for the selected buffer.
Parameters:
/* free the current buffer */ options results address PHOTOGENICS.1 BUFFER CLOSE result
Format: COMPOSE - main second x y x1 y1 settings
Function: The second image is composed into the main buffer at the coordinates given using the selected settings.
Parameters:
Limitations:Doesn't currently allow other paintmodes to be used. This will be fixed soon.
Format: CROP buffer x y width height
Function: Crops an image buffer to the rectangle with top left coordinate x,y, width pixels wide and height pixels high.
Parameters:
Example:
/* crop the current buffer */ options results address PHOTOGENICS.1 BUFFER CROP result 10 10 50 50
Format: DEPTH buffer
Function: The number of bits per pixel of the image is returned.
Parameters: buffer = a pointer to the buffer returned by NEW, LOAD or LOADGIO
Function returns: result is the bits per pixel value
Notes:Currently only 24-bit buffers are supported, so 24 is always returned. Future versions will support other bit depths.
Format: EFFECT buffer effect [parameters]
Function: The selected effect is appled to the whole image.
Parameters:
Notes:Always keep the effect name in quotes, or AREXX will upper-case it and Photogenics won't be able to find it.
Format: EFFECTAREA buffer effect [parameters]
Function: The selected effect is appled to the chosen region of the image.
Parameters:
Notes:Always keep the effect name in quotes, or AREXX will upper-case it and Photogenics won't be able to find it.
Format: EFFECTPAINT buffer effect [parameters]
Function: The selected effect is appled to the paintlayer of an image.
Parameters:
Notes:Always keep the effect name in quotes, or AREXX will upper-case it and Photogenics won't be able to find it.
Format: ELLIPSE buffer x y w h
Function: Draws an ellipse (or circle) into buffer using the current brush tool, center at x,y, width w and height h.
Parameters:
Format: ELLIPSEFILL buffer x y w h
Function: Draws a filled ellipse (or circle) into buffer. Center at x,y, width w and height h.
Parameters:
Format: FILENAME buffer
Function: Returns the original path and filename of the image.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Function returns: result - a string containing the full path and filename.
Format: FILLIMAGE buffer
Function: The paintlayer (the 8-bit transparency channel you paint
into) is filled with a solid colour (or a gradient pattern depending on the
currently selected gradient).
Parameters: buffer = a pointer to the buffer returned by NEW, LOAD
or LOADGIO
Example:
/* Open an image and fill the paintlayer */ options results address PHOTOGENICS.1 LOAD "ram:text.jpg" FILLIMAGE result
Format: FIX buffer
Function: Makes changes applied to buffer permanent.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Example:
/* fix changes in the currently selected buffer */ options results address PHOTOGENICS.1 BUFFER FIX result
Format: FIXKEEP buffer
Function: Makes changes applied via the paintlayer permanent, but unlike FIX the contents of the paintlayer are not cleared, so further operations can be carried out.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Format: GETLINE buffer y
Function: A powerful function which must be used with care.
GETLINE provides access to the 24-bit internal data stored in Photogenics.
This returns the address of the 24-bit data, which you can then manipulate
as you wish. The data is stored in RGBRGBRGB... format, with 1 byte per
colour component, three bytes per pixel, no pad data.
Parameters:
Notes: ALWAYS RELEASELINE after you have finished accessing the data. Do NOT attempt any other photogenics operations that alter the image data (FIX, SCALE, CROP, etc.) while you have a line locked. Do NOT GETLINE more lines at a time than you need, although it is safe to allocate more than one at a time, as long as they are all released when finished with. NEVER access the data after RELEASELINE has been called.
Limitations:Does not support Virtual Images yet.
Format: GETPAINTMODE buffer
Function: Get the paintmode currently selected for this buffer.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Function returns: The name of the paintmode.
Format: GETTRANSLINE buffer y
Function: A powerful function which must be used with care.
GETTRANSLINE provides access to the 8-bit internal data for the paintlayer
stored in Photogenics. This returns the address of the 8-bit data, which
you can then manipulate as you wish. The data is stored with 1 byte per
pixel, no pad data. 0 is transparent, 255 is opaque (assuming the
transparency slider is set to 0%)
Parameters:
Notes: ALWAYS RELEASETRANSLINE after you have finished accessing the data. Do NOT attempt any other photogenics operations that alter the image data (FIX, SCALE, CROP, etc.) while you have a line locked. Do NOT GETTRANSLINE more lines at a time than you need, although it is safe to allocate more than one at a time, as long as they are all released when finished with. NEVER access the data after RELEASETRANSLINE has been called.
Format: HEIGHT buffer
Function: Used to determine the height of a Photogenics image buffer.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Function returns: height in pixels.
Example:
/* display the height of the currently selected buffer */ options results address PHOTOGENICS.1 BUFFER HEIGHT result say "Image is " || result || " pixels high"
Format: HELP
Function: Open the Photogenics on-line help.
Format: INVERTALPHA
Function: The Alpha Channel is inverted.
Format: INVERTPAINT buffer
Function: The paintlayer is inverted.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO, NEW, etc.
Format: ISVALID buffer
Function: Checks to see if a buffer is alive in Photogenics - useful for making scripts bombproof.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO, NEW, etc.
Function returns: rc is set to zero if the specified buffer is valid within Photogenics, 1 otherwise.
Format: KPRINTF string
Function: Prints a string to the serial port. This is useful for debugging purposes.
Parameters: string - A string.
Notes: Written for our own debugging purposes. You may find this a
useful way to monitor script process (if you have a serial terminal
attached to your Amiga serial port.)
Format: LINE buffer x y x1 y1
Function: Draws a line in the current brush into the image starting
at coordinates x,y and ending at x1,y1. This is the equivelant of a single
click on the image at the given coordinates with the standard drawing
tool.
Parameters:
Format: result LISTBRUSHES
Function: Return a list of all the brushes currently available in Photogenics.
Function returns: A string containing all available brushes, each
seperated by a space.
Format: result LISTEFFECTS
Function: Return a list of all the effects currently available in Photogenics.
Function returns: A string containing all available effects, each
seperated by a space.
Format: result LISTLOADERS
Function: Return a list of all the loaders currently available in Photogenics.
Function returns: A string containing all available loaders, each
seperated by a space.
Format: result LISTMODES
Function: Return a list of all the paintmodes currently available in Photogenics.
Function returns: A string containing all available paintmodes,
each seperated by a space.
Format: result LISTSAVERS
Function: Return a list of all the savers currently available in Photogenics.
Function returns: A string containing all available savers, each
seperated by a space.
Format: LOAD filename
Function: Photogenics attempts to load a file.
Parameters: filename - The name of the file to load.
Function returns: Buffer is a unique pointer to the image buffer. This result is used as a lock on the image for all further operations. rc = 0 on success, 1 if there was any problems preventing the image loading.
Notes: It is *slightly* faster and more memory efficient to use LOADGIO and specify the GIO type if you know what type of file you are loading (for example if converting a batch of JPEG files). Otherwise use LOAD, which avoids having to specify the file type and will automatically detect the filetype (where possible). You will also need to use LOADGIO if you wish to pass ARexx parameters to the loader (to override requesters, for example)
Example:
/* Open an image */ address PHOTOGENICS.1 LOAD "ram:text.jpg"
Format: LOADGIO loadername [filename] [options]
Function: Photogenics attempts to load/create a new image using the
import filter specified in loadername (the .GIO suffix must not be used).
If a disk file is being loaded, the filename must be specified. Each GIO
has different options, and these may need to be specified. See the arexx
documentation for the GIO files to determine what options are needed.
Parameters:
Notes: It is *slightly* faster and more memory efficient to use LOADGIO and specify the GIO type if you know what type of file you are loading (for example if converting a batch of JPEG files). Otherwise use LOAD, which avoids having to specify the file type and will automatically detect the filetype (where possible)
Example:
/* Open an image */ address PHOTOGENICS.1 LOADGIO "JPEG" "ram:text.jpg"
Format: LOADHIDE filename
Function: Photogenics attempts to load a file.
Parameters: filename - The name of the file to load.
Function returns: Buffer is a unique pointer to the image buffer.
This result is used as a lock on the image for all further operations. rc
= 0 on success, 1 if there was any problems preventing the image loading.
Notes: It is *slightly* faster and more memory efficient to use LOADGIO and specify the GIO type if you know what type of file you are loading (for example if converting a batch of JPEG files). Otherwise use LOAD, which avoids having to specify the file type and will automatically detect the filetype (where possible). You will also need to use LOADGIO if you wish to pass ARexx parameters to the loader (to override requesters, for example)
Example:
/* Open an image */ address PHOTOGENICS.1 LOADHIDE "ram:text.jpg"
Format: LOADHIDEGIO loadername [filename] [options]
Function: Photogenics attempts to load/create a new image using the
import filter specified in loadername (the .GIO suffix must not be used).
If a disk file is being loaded, the filename must be specified. Each GIO
has different options, and these may need to be specified. See the arexx
documentation for the GIO files to determine what options are needed.
Unlike LOADGIO, the image does not have a new window created for it (it is
hidden, as in the Open As/Hidden menu item in Photogenics)
Parameters:
Notes: It is *slightly* faster and more memory efficient to use LOADGIO and specify the GIO type if you know what type of file you are loading (for example if converting a batch of JPEG files). Otherwise use LOAD, which avoids having to specify the file type and will automatically detect the filetype (where possible)
Example:
/* Open an image */ address PHOTOGENICS.1 LOADHIDEGIO "JPEG" "ram:text.jpg"
Format: LOADVIRT filename
Function: Photogenics attempts to load a file as a virtual image.
Parameters: filename - The name of the file to load.
Function returns: 'buffer' is a unique pointer to the virtual
image buffer. This result is used as a lock on the image for all further
perations. rc = 0 on success, 1 if there was any problems preventing the
image loading.
Format: MODEOPTS buffer options
Function: Change the mode options for the paintmode selected on the chosen buffer.
Parameters:
Format: NEW x y r g b
Function: Create a new image, size x,y colour rgb.
Parameters:
Example:
/* Create a new image */ address PHOTOGENICS.1 NEW 320 256 200 100 50
Format: NEWVIRT x y
Function: Create a new virtual image, size x,y.
Parameters:
Example:
/* Create a new virtualimage */ address PHOTOGENICS.1 NEWVIRT 320 256 200 100 50
Format: OPENPROGRESS title text
Function: In complex arexx scripts a progress meter can be
displayed. While this is active no standard Photogenics
requesters will be opened (eg other progress meters) and redrawing of
windows will be switched off. (A lot of CPU time is normally spent doing
the chunky-planar conversions to bring 24-bit data to the Amiga video
system)
Parameters:
Example:
/* display a progress requester */ options results address PHOTOGENICS.1 OPENPROGRESS "Progress" "'Default text in progress meter'" SETPROGRESS "" 0 < do something > SETPROGRESS "" 50 < do something else > SETPROGRESS "" 100 < finished > CLOSEPROGRESS
Spaces in strings are best dealt with by enclosing text in double quotes , eg. "'xx xx xx'"
Format: PAINTMODE buffer paintmode
Function: A new paintmode is selected for the chosen buffer.
Parameters:
Example:
/* Change the paintmode to Negative */ options results address PHOTOGENICS.1 BUFFER PAINTMODE result "Negative"
Format: PAINTTOALPHA buffer
Function: The paintlayer is transferred from the current image to a new alpha channel buffer.
Parameters: buffer - A buffer pointer previously returned by NEW, BUFFER, LOADGIO, LOAD, etc.
Notes: Follow this with an ALPHA command to get the ID of the Alpha Channel it creates.
Format: PGSTOBACK - Send Photogenics screen to back.
Function: The Photogenics screen is sent to the back of the visible
screen list, hiding behind other open screens.
Format: PGSTOFRONT - Send Photogenics screen to front.
Function: The Photogenics screen is sent to the front of the
visible screen list..
Format: PLOT buffer x y
Function: Draw the current brush into the image at co-ordinates x,y
This is the equivelant of a single click on the image at the given
coordinates with the standard drawing tool.
Parameters:
Format: PRESSURE val
Function: Sets the brush pressure (in percent)
Parameters: val - the pressure required (1 to 100)
Format: QUIT
Function: Quits Photogenics
Format: RECT buffer x y x1 y1
Function: Draws a rectangle into buffer using the current brush tool.
Top left corner = x,y. Bottom right corner = x1,y1
Parameters:
Format: RECTFILL buffer x y x1 y1
Function: Draws a filled rectangle into buffer
Top left corner = x,y. Bottom right corner = x1,y1
Parameters:
Format: REDRAW buffer
Function: Redraw the window display for a buffer.
Parameters: buffer - pointer to a buffer (returned by NEW, etc.)
Notes: Should be used if you access the buffer via GETLINE/RELEASELINE, and at the end of scripts after you have finished processing while redraw has been turned off (with OPENPROGRESS, for example)
Format: RELEASELINE buffer y
Function: Call this when you have finished manipulating data
accesssed by GETLINE. To refresh the Photogenics window after this, call
REDRAW buffer
Parameters:
Limitations:Does not support Virtual Images yet.
Format: RELEASETRANSLINE buffer y
Function: Call this when you have finished manipulating data
accesssed by GETTRANSLINE. To refresh the Photogenics window after this,
call REDRAW buffer.
Parameters:
Format:RENAME buffer newname
Function: Renames a buffer, or virtual image with the new title.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD,
LOADGIO, NEW, NEWVIRT, LOADVIRT, etc.
Format: RESIZETILED buffer newx newy
Function: Resizes an image buffer to new size of newx newy,
the original image is tiled to fit the new space.
Parameters:
Format: ROTATE buffer angle
Function: Rotate a Photogenics image buffer.
Parameters:
Notes: Image is scaled to fit the minimum dimensions of the rotated image. No image data is lost off the sides, so if you need to keep the resultant image the same size either crop the new area off, or see the Perspective effect (use it to rotate in the z axis only)
Format: SAVE buffer gioname filename [options]
Function: Save the buffer from Photogenics using the gio specified.
Parameters:
Example:
/* Save the current image */ options results address PHOTOGENICS.1 BUFFER SAVE result "JPEG" "ram:test.jpg" 90 /* 90 is the quality field for JPEG saves */
Format:SAVECLIP buffer
Function: Saves a clip back to the virtual image it was clipped
from.
Parameters: buffer - pointer to a buffer clipped from a Virtual Image (created with the VCLIP function)
Notes: Only works if the image was clipped from a virtual image, of course! You don't need to tell it where it was clipped from, it's got a good memory :-)
Format:SCALE buffer newx newy (SMOOTH | NORMAL)
Function: Scales an image buffer to new size of newx newy.
Parameters:
(one of NORMAL or SMOOTH is required.)
Example:
/* scale the current buffer */ options results address PHOTOGENICS.1 BUFFER SCALE result 150 150 SMOOTH
Format: SECONDARY
Function: Return a pointer to the current secondary image, if one is
selected within Photogenics.
Function returns: 'buffer' is a unique pointer to the secondary
image buffer. This result is used as a lock on the image for all further
operations. rc = 0 on success, 1 if there was no secondary image.
Format:SELECTSIM buffer tolerance smooth r g b
Function: Select all regions of the image matching the r g b values
provided within the tolerance given, using the smoothness factor depending
on their distance from the given RGB value.
Parameters:
Limitations: Don't set smoothness to zero. Bad things might happen.
Format: SETALPHA buffer
Function: Select the image as the alpha channel
Parameters: buffer - pointer to image buffer.
Format: SETIMAGE buffer
Function: Select the image as a normal image (Cancels alpha and/or
secondary setting)
Parameters: buffer - pointer to image buffer.
Format: SETPROGRESS text percent
Function: Sets the state of the progress meter.
Parameters:
Notes: Must be done after OPENPROGRESS, and before CLOSEPROGRESS!
Format: SETSECONDARY buffer
Function: Select the image as the secondary image.
Parameters: buffer - pointer to image buffer.
Format: SHEAR buffer xshift yshift
Function: Shear a Photogenics image buffer.
Parameters:
Format: SHOWERROR string
Function: An error requester containing 'string' is displayed and
script execution paused until the requester is closed.
Parameters: string - ascii text
Example:
/* show an error requester */ address PHOTOGENICS.1 SHOWERROR "Not enough memory to continue"
Format: SHOWMESSAGE title string
Function: A message requester containing 'string' is displayed and
script execution paused until the requester is closed.
Parameters:
/* show an error requester */ address PHOTOGENICS.1 SHOWMESSAGE "Ready" "Press OK to continue with script"
Format: TRANSFIX buffer
Function: The transparency level is set back to 100%, but the
paintlayer is altered so it matches the previous
appearance with the old transparency level.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Format: TRANSGRAD mode
Function: The gradient type is selected for FILLSCREEN, RECTFILL,
ELLIPSEFILL and other Photogenics operations.
Parameters:
Format: TRANSPARENCY buffer value
Function: Set the value for the paintlayer transparency.
Parameters:
Format: UNDO buffer
Function: Undo fixed changes to a buffer.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD,
LOADGIO or NEW.
Example:
/* undo changes to the currently selected buffer */ options results address PHOTOGENICS.1 BUFFER UNDO result
Format: VCLIP vimage x y x1 y1
Function: Clips out an area of a Virtual Image into a new
(non-virtual) buffer. This buffer is returned and can be acted on.
Parameters:
Function returns: buffer - a pointer to the buffer (non-virtual) containing the clipped region.
Format: WARPER buffer x y w h cx cy factor twirl
Function: Photogenics will warp the area of the image with the specified parameters.
Parameters:
Function returns: Eventually... :-)
Example:
/* Warp an image */ options results address PHOTOGENICS.1 BUFFER WARPER result 100 50 30 30 120 70 0 60
Format: WIDTH buffer
Function: Used to determine the width of a Photogenics image buffer.
Parameters: buffer - pointer to a buffer returned by BUFFER, LOAD, LOADGIO or NEW
Function returns: width in pixels.
Example:
/* display the width of the currently selected buffer options results address PHOTOGENICS.1 BUFFER WIDTH result say "Image is " || result || " pixels wide"