What is Image.opx?
IMAGE.OPX is an OPL extension library that allows you to load and save images in a range of different formats (BMP,JPG,PNG,GIF,ICO etc) from within OPL. Features include getting pixel color information from OPL bitmaps, loading all kinds of graphics formats (including transparency), saving into different graphics formats and image rescaling, flipping and rotating.
Which graphics formats can be read and written by IMAGE.OPX depends on the number of graphics converter libraries that are installed on your Communicator. By default converters for the formats BMP, JPG, PNG, ICO, TIFF,GIF, WBMP, WMF and OTA are installed on 9300/9500 devices, but there may be additional formats if extra converters are installed.
Note: IMAGE.OPX only runs on S80 devices (Nokia 9300/9500).
Download Image.opx
You can download Image.opx from the Downloads page.
Usage
To use IMAGE.OPX, use the following statement at the beginning of your OPL application:
INCLUDE "IMAGE.OXH"
Installing IMAGE.OPX
To install Image.opx, double click on the IMAGEOPX_S80.SIS-file in Windows Explorer or copy it to your device and open it from the FileManager application. After this, copy the Image.oxh file to the \SYSTEM\OPL folder on either drive C: or drive D:
Bugs or improvements
If you find any bugs or have further ideas for improvement, please let me know by sending an email to Arjen Broeze or by posting a message in the OPX and OPM support forum.
Documentation of IMAGE.OPX functions
imgBitmapGet&:(aWindowId%)
Retrieves a handle to the bitmap. The ID specified in the aWindowId% parameter can either be the ID of an OPL window (created with gCREATE) or the ID of an OPL bitmap (created with gCREATEBIT).
imgBitmapFree:(aBitmapHandle&)
Frees the handle to the bitmap previously retrieved with the imgBitmapGet&: function.
imgBitmapGetPixel&:(aBitmapHandle&,aXPos%,aYPos%)
After a call to imgBitmapGet&: you can use imgBitmapGetPixel to get the RGB value of any pixel in the image. The value is returned in the following form 0xRRGGBB and can be converted to Red, Green and Blue values in the following way:
REM Get the bitmap of the main window
bmp&=imgBitmapGet&:(1)
REM Get the pixel at position 10,10
REM X and Y coordinates range from 0 to Width-1, resp Height-1
RGB&=imgBitmapGetPixel&:(bmp&,9,9)
REM Free the retrieved handle
imgBitmapFree:(bmp&)
REM Convert RGB value into Red%, Green% and Blue% values
Red%=RGB&/KRgbRedPosition& AND KRgbColorMask&
Green%=RGB&/KRgbGreenPosition& AND KRgbColorMask&
Blue%=RGB&/KRgbBluePosition& AND KRgbColorMask%
imgOpen&:(aFileName$)
This function opens the image specified in the aFileName$ parameter and returns a handle to the opened file. If the file format cannot be recognized or the file cannot be opened, an error is raised. The returned handle can be used to get information about the image (like the number of frames (for example for MBM and GIF), the width,height and colordepth of each frame and whether or not the image is transparent).
imgClose:(aImage&)
Closes the image file previously opened with the imgOpen&: function.
imgFrameCount%:(aImage&)
Returns the number of frames in the opened image file. For a lot of formats this is always 1, but GIF and MBM image files for example can have more than one frame.
imgFrameWidth%:(aImage&,aFrame%)
Returns the width of the frame specified by the aFrame% parameter. The value of the aFrame% parameter must be between 0 and (imgFrameCount%: - 1) otherwise an error will be raised.
imgFrameHeight%:(aImage&,aFrame%)
Returns the height of the frame specified by the aFrame% parameter. The value of the aFrame% parameter must be between 0 and (imgFrameCount%: - 1) otherwise an error will be raised.
imgFrameDisplayMode%:(aImage&,aFrame%)
Returns the display mode (color depth) of the frame specified by the aFrame% parameter. The value of the aFrame% parameter must be between 0 and (imgFrameCount%: - 1) otherwise an error will be raised.
imgFrameTransparencyPossible%:(aImage&, aFrame%)
Returns KTrue% when the frame specified by the aFrame% parameter can be displayed transparent, KFalse% otherwise. The value of the aFrame% parameter must be between 0 and (imgFrameCount%: - 1) otherwise an error will be raised.
imgFrameLoad:(aImage&,aFrame%,aBitmap%,aMode%)
Loads the image from the frame specified by the aFrame% parameter into the OPL bitmap specified by the aBitmap% parameter. The value of the aFrame% parameter must be between 0 and (imgFrameCount%: - 1) otherwise an error will be raised. How the bitmap is drawn depends on the value of the aMode% parameter:
| aMode% | Effect | |
| KImgLoadDefault% | Loads the frame unmodified in the bitmap. If the frame size is smaller than the bitmap the leftover area will not be painted, if the frame size is larger than the bitmap, the image will be clipped | |
| KImgLoadScale% | Scales the frame to the size of the bitmap specified in the aBitmap% parameter. Due to this scaling the aspect ratio of the image may change. |
Note: the bitmap must be an OPL bitmap (created with gCREATEBIT). Due to limitations in the OPL Runtime it is not possible to draw on OPL-Windows from within an OPX.
An example:
REM Open the image
img&=imgOpen&:("C:\Test.jpg")
REM JPG files only have one frame so we don't use the
REM imgFrameCount%: function here
iWidth%=imgFrameWidth%:(img&,0)
iHeight%=imgFrameHeight%:(img&,0)
iMode%=imgFrameDisplayMode%:(img&,0)
REM Now that we have the information, create a bitmap to load
REM the image into
bmp%=gCREATEBIT(iWidth%,iHeight%,iMode%)
REM Load the image into the bitmap and close the image file
imgFrameLoad:(img&,0,bmp%,KImgLoadDefault%)
imgClose:(img&)
REM The image is now loaded into bmp% and can be displayed on the
REM main OPL window
gUSE 1
gAT 0,0
gCOPY bmp%,0,0,iWidth%,iHeight%,3
gCLOSE bmp%
imgFrameLoadTransparent:(aImage&,aFrame%,aBitmap%,aMask%,aMode%)
Loads the image from the frame specified by the aFrame% parameter into the OPL bitmaps specified by the aBitmap% and aMask% parameters. The value of the aFrame% parameter must be between 0 and (imgFrameCount%: - 1) otherwise an error will be raised. See imgFrameLoad: for details the aMode% parameter. This function raises an error if the frame does not contain transparency information. To determine whether or not a frame can be displayed transparent use the imgFrameTransparencyPossible%: function.
Note: the bitmap must be an OPL bitmap (created with gCREATEBIT). Due to limitations in the OPL Runtime it is not possible to draw on OPL-Windows from within an OPX.
An example:
img&=imgOpen&:("C:\Test.gif")
IF NOT imgFrameTransparencyPossible%:(img&,0)
ALERT("Image cannot be displayed transparent")
STOP
ENDIF
iWidth%=imgFrameWidth%:(img&,0)
iHeight%=imgFrameHeight%:(img&,0)
iMode%=imgFrameDisplayMode%:(img&,0)
bmp%=gCREATEBIT(iWidth%,iHeight%,iMode%)
mask%=gCREATEBIT(iWidth%,iHeight%,iMode%)
imgFrameLoadTransparent:(img&,0,bmp%,mask%,KImgLoadDefault%)
imgClose:(img&)
REM The image is now loaded into bmp% and mask% and can be
REM displayed on the main OPL window
gUSE 1
gAT 0,0
gCOPY mask%,0,0,iWidth%,iHeight,1
gCOPY bmp%,0,0,iWidth%,iHeight%,0
gCLOSE bmp%
gCLOSE mask%
Saving an image into a specific image format consists of two steps:
imgResetImageData:
This function resets all the image saving options to their default values and should be called before setting new options.
imgSetMbmData:(aDisplayMode%)
If you want to save an image into MBM format, you can use the imgSetMbmData: function to specify the color depth of the saved image. The aDisplayMode% parameter can take any of the values specified in CONST.OPH that can also be used for creating windows and bitmaps, for example KgCreate4KColorMode%.
imgSetBmpData:(aBitsPerPixel%)
If you want to save an image into BMP format, you can use the imgSetBmpData: function to specify the color depth of the saved image. The aBitsPerPixel% parameter can take any value between 1 and 24, where 1 corresponds to a black and white image and 24 corresponds to an image with 64 million colors.
imgSetJpgData:(aColorSampling%,aQualityFactor%)
If you want to save an image into JPG format, you can use the imgSetJpgData: function to specify the color depth of the saved image. Valid values for the aColorSampling% parameter are KImgJpgImageMonochrome%, KImgJpgImageColor420%, KImgJpgImageColor422% and KImgJpgImageColor444% and can be found in Image.oxh. The aQualityFactor% is a percentage between 1 and 100. Larger values usually generate better quality images, but the resulting images take up a lot more disk space.
imgSetPngData:(aCompressLevel%,aBitsPerPixel%,aColor%,aPaletted%)
If you want to save an image into PNG format, you can use the imgSetPngData: function to specify the compression level, color depth, color/monochrome and whether the image should be saved with a palette. Valid values for the aCompressLevel% parameter are KImgPngDefaultCompression%, KImgPngNoCompression%, KImgPngBestSpeedCompression% and KImgPngBestCompression% and can be found in Image.oxh. The aBitsPerPixel% parameter can take any value between 1 and 24, where 1 corresponds to a black and white image and 24 corresponds to an image with 64 million colors.
imgSave%:(aBitmap%,aFileName$,aImageType%)
Saves the image specified in the aBitmap% parameter to the file specified in the aFileName$ parameter and return 0 is the image was saved successfully or one of the system wide error codes otherwise. The aImageType% parameter specifies the image format. Values for the aImageType% parameter can be found in Image.oxh (KImgTypeXXXXX%).
imgDrawBitmap:(aSource%,aSrcLeft%,aSrcTop%,aSrcWidth%,aSrcHeight%,aDest%,aDestLeft%,aDestTop%,aDestWidth%,aDestHeight%)
Draws and if necessary scales the part of the bitmap specified by the aSrcLeft%, aSrcTop%, aSrcWidth% and aSrcHeight% parameters from the bitmap specified in the aSource% parameters onto the rectangle specified in the aDestLeft%, aDestTop%, aDestWidth% and aDestHeight% in the bitmap specified by the aDest% parameter.
If the destination rectangle falls outside the boundaries of the aDest% bitmap, the resulting image will be clipped at the boundaries of the aDest% bitmap.
Note: the aDest% bitmap must be an OPL bitmap (created with gCREATEBIT). Due to limitations in the OPL Runtime it is not possible to draw on OPL-Windows from within an OPX.
Example:
The following example takes an image in bmp1% and scales it to fit the screen retaining the aspect ratio. It is assumed that bmp1% is an existing bitmap. The scaled picture is stored in bmp2%:
REM Retrieve the width and height of the original image
gUSE bmp1%
iWidth%=gWIDTH
iHeight%=gHEIGHT
REM Calculate the max width and height depending on the height
REM and width of the main window
iNewWidth%=iWidth%
iNewHeight%=iHeight%
REM Calculate new width and height
gUSE 1
IF iNewWidth%>gWIDTH
iNewHeight%=INT(FLT(iNewHeight%)*(FLT(gWIDTH)/FLT(iWidth%)))
iNewWidth%=gWIDTH
ELSE
iNewWidth%=INT(FLT(iNewWidth%)*(FLT(gHEIGHT)/FLT(iHeight%)))
iNewHeight%=gHEIGHT
ENDIF
REM Create a new bitmap with this size
bmp2%=gCREATEBIT(iNewWidth%,iNewHeight%,iMode%)
REM Stretch/shrink the bitmap in bmp% to bmp2%
ImgDrawBitmap:(bmp1%,0,0,iWidth%,iHeight%,bmp2%,0,0,iNewWidth%,iNewHeight%)
REM Draw the bitmap centered on the screen
gUSE 1
gCLS
gAT (gWIDTH-iNewWidth%)/2,(gHEIGHT-iNewHeight%)/2
gCOPY bmp2%,0,0,iNewWidth%,iNewHeight%,3
GET
gCLOSE bmp2%
imgRotateBitmap:(aSource%,aDest%,aAngle%)
Rotates or flips the image specified in the aSource% parameter and returns the modified image in the aDest% parameter. The aAngle% parameter specifies how to rotate or flip the image and can have one of the following values:
KImgRotation90DegreesClockwise%
KImgRotation180DegreesClockwise%
KImgRotation270DegreesClockwise%
KImgMirrorHorizontalAxis%
KImgMirrorVerticalAxis%
Note: the aDest% bitmap must be an OPL bitmap (created with gCREATEBIT) and must have the correct dimensions. For 180 degrees rotation or horizontal or vertical flipping the dimensions of aDest% must be equal to aSource%. For the 90 and 270 degrees rotation the dimensions of aDest% must be the swapped height and width of aSource%. For example if aSource% is 200 pixels wide and 100 pixels tall, the dimensions of the aDest% bitmap must be (100,200).
Example:
This example rotates the image in bmp1% 90 degrees clockwise. It is assumed that bmp1% is an existing bitmap. The rotated result is stored in bmp2%:
gUSE bmp1%
iWidth%=gWIDTH
iHeight%=gHEIGHT
REM Create a new bitmap, but swap height and width
bmp2%=gCREATEBIT(iHeight%,iWidth%,KgCreate4KColorMode%)
REM Rotate the bitmap 90 degrees
imgRotateBitmap:(bmp1%,bmp2%,KImgRotation90DegreesClockwise%)
REM Display the rotated bitmap
gUSE 1
gCLS
gAT 0,0
gCOPY bmp2%,0,0,iHeight%,iWidth%,3
GET
gCLOSE bmp2%
IMAGE.OXH
REM Image.oxh
REM
REM Copyright (c) 2005 Arjen Broeze. All rights reserved.
REM
CONST KUidOpxImage&=&1020834B
CONST KOpxImageVersion%=$110
CONST KImgLoadDefault%=1
CONST KImgLoadScale%=2
CONST KImgTypeBMP%=1
CONST KImgTypeGIF%=2
CONST KImgTypeWMFStd%=3
CONST KImgTypeWMFApm%=4
CONST KImgTypeWMFClp%=5
CONST KImgTypeTIFFLittleEndian%=6
CONST KImgTypeTIFFBigEndian%=7
CONST KImgTypePNG%=8
CONST KImgTypeMBM%=9
CONST KImgTypeWBMP%=10
CONST KImgTypeOTA%=11
CONST KImgTypeICO%=12
CONST KImgTypeJPG%=13
CONST KImgJpgImageMonochrome%=1
CONST KImgJpgImageColor420%=2
CONST KImgJpgImageColor422%=3
CONST KImgJpgImageColor444%=4
CONST KImgPngDefaultCompression%=1
CONST KImgPngNoCompression%=2
CONST KImgPngBestSpeedCompression%=3
CONST KImgPngBestCompression%=4
CONST KImgRotation90DegreesClockwise%=1
CONST KImgRotation180DegreesClockwise%=2
CONST KImgRotation270DegreesClockwise%=3
CONST KImgMirrorHorizontalAxis%=4
CONST KImgMirrorVerticalAxis%=5
DECLARE OPX Image,KUidOpxImage&,KOpxImageVersion%
imgBitmapGet&:(aWindowId%) :1
imgBitmapFree:(aBitmapHandle&) :2
imgBitmapGetPixel&:(aBitmapHandle&,aXPos%,aYPos%) :3
imgOpen&:(aFileName$) :4
imgClose:(aImage&) :5
imgFrameCount%:(aImage&) :6
imgFrameWidth%:(aImage&, aFrame%) :7
imgFrameHeight%:(aImage&, aFrame%) :8
imgFrameDisplayMode%:(aImage&, aFrame%) :9
imgFrameLoad:(aImage&,aFrame%,aBitmap%,aMode%) :10
imgResetImageData: :11
imgSetMbmData:(aDisplayMode%) :12
imgSetBmpData:(aBitsPerPixel%) :13
imgSetJpgData:(aColorSampling%,aQualityFactor%) :14
imgSetPngData:(aCompressLevel%,aBitsPerPixel%,aColor%,aPaletted%) :15
imgSave%:(aBitmap%,aFileName$,aImageType%) :16
imgDrawBitmap:(aSource%,aSrcLeft%,aSrcTop%,aSrcWidth%,aSrcHeight%,aDest%,aDestLeft%,aDestTop%,aDestWidth%,aDestHeight%) :17
imgFrameTransparencyPossible%:(aImage&, aFrame%) :18
imgFrameLoadTransparent:(aImage&,aFrame%,aBitmap%,aMask%,aMode%) :19
imgRotateBitmap:(aSource%,aDest%,aAngle%) :20
END DECLARE