GBMRX has a simple and straightforward API consisting of 18 functions.
A typical usage in a REXX program looks like this:
/* My REXX program */
call RxFuncAdd 'GBM_LoadFuncs', 'GBMRX', 'GBM_LoadFuncs'
call GBM_LoadFuncs
/*** Show the format info a bitmap ***/
rc = GBM_FileType('myfile.gif', 'type.')
if rc = "0" then
do
say '----------------------'
say ' Extensions: 'type.extensions
say ' Short desc: 'type.shortname
say ' Long desc: 'type.longname
end
else
do
say
say '### Cannot detect bitmap type.'
say rc
end
call GBM_DropFuncs
Please have a look at the included script example_gbmrx.cmd
for a more complete example.
The following API functions are available since the specified version of GBMRX:
Function: GBM_LoadFuncs Syntax : call GBM_LoadFuncs Params : none Info : Registers all functions and procedures of GBMRX module. Example : /* Code in the procedure */ call RxFuncAdd 'GBM_LoadFuncs', 'GBMRX', 'GBM_LoadFuncs' call GBM_LoadFuncs
Function: GBM_DropFuncs Syntax : call GBM_DropFuncs Params : none Info : Unregisters all functions and procedures of GBMRX module. Example : /* Code in the procedure */ call GBM_DropFuncs
Function: GBM_Version Syntax : version = GBM_Version() Params : none Return : "major.minor" The version number of used GBM.DLL. Info : Query version number of the used GBM.DLL module. Example : /* Code in the procedure */ version = GBM_Version()
Function: GBM_VersionRexx Syntax : version = GBM_VersionRexx() Params : none Return : "major.minor" The version number of GBMRX.DLL. Info : Query version number of GBMRX module. Example : /* Code in the procedure */ version = GBM_VersionRexx()
Function: GBM_Types
Syntax : rc = GBM_Types('stem')
Params : stem out - bitmap format information consisting of
stem.0 : number of info blocks
stem.X.extensions: bitmap extensions
stem.X.shortname : short description
stem.X.longname : long description
X: Ranging from 1 to stem.0
Return : "0", an error message or "ERROR" for an unknown error
Info : Queries information about all supported bitmap formats.
Example :
/* Code in the procedure */
rc = GBM_Types('types.')
if rc = "0" then
do
say 'Number of supported formats: 'types.0
say '----------------------'
do i = 1 to types.0
say ' Extensions: 'types.i.extensions
say ' Short desc: 'types.i.shortname
say ' Long desc: 'types.i.longname
if i < types.0 then
do
say '----------------------'
end
end
end
Function: GBM_IsBppSupported
Syntax : sup = GBM_IsBppSupported(fileExtension, bpp, rw)
Params : string in - the filetype extension reported by GBM_Types
string in - bpp (bits per pixel) to test
string in - "r" for testing for read support
"w" for testing for read support
Return : "0" (unsupported) or "1" (supported)
Info : Test whether the input or output bitmap format
supports the specified colour depth.
Example :
/* Code in the procedure */
sup = GBM_IsBppSupported('GIF', 8, 'w')
if sup = "1" then
do
say 'Colour depth is supported by output format'
end
Function: GBM_FileType
Syntax : rc = GBM_FileType(filename, 'stem')
Params : string in - filename
stem out - bitmap format information consisting of
stem.extensions: bitmap extensions
stem.shortname : short description
stem.longname : long description
Return : "0", an error message or "ERROR" for an unknown error
Info : Queries the bitmap format of the specified file.
Note: This function does only check the codec database
but not the file content (and there only the extensions).
Use GBM_FileHeader for this.
Example :
/* Code in the procedure */
rc = GBM_FileType(filename, 'type.')
if rc = "0" then
do
say ' Extensions: 'type.extensions
say ' Short desc: 'type.shortname
say ' Long desc: 'type.longname
end
Function: GBM_FilePages
Syntax : rc = GBM_FilePages(filename [, fileExtension])
Params : string in - filename
string in - the optional filetype extension reported
by GBM_Types to override autodetection
based on the file extension.
Return : "0", an error message or "ERROR" for an unknown error
Info : Queries the number of pages in the specified file.
Note: This function requires GBM.DLL version 1.35 or higher.
Example :
/* Code in the procedure */
numPages = GBM_FilePages(filename)
say 'Number of pages: 'numPages
Function: GBM_FileHeader
Syntax : rc = GBM_FileHeader(filename, options, 'stem' [, fileExtension])
Params : string in - filename
string in - comma separated options
(see GBM format documentation)
stem out - header information consisting of
stem.width : bitmap width
stem.height: bitmap height
stem.bpp : bitmap colour depth (bpp)
string in - the optional filetype extension reported
by GBM_Types to override autodetection
based on the file extension.
Return : "0", an error message or "ERROR" for an unknown error
Info : Reads the bitmap header of the specified bitmap file.
Additional options (see GBM format documentation) may
be specified, e.g. "index=2".
Example :
/* Code in the procedure */
rc = GBM_FileHeader(filename, '', 'header.')
if rc = "0" then
do
say ' Bitmap width : 'header.width
say ' Bitmap height: 'header.height
say ' Bitmap bpp : 'header.bpp' bpp'
end
Function: GBM_FilePalette
Syntax : rc = GBM_FilePalette(filename, options, 'stem' [, fileExtension])
Params : string in - filename
string in - comma separated options
(see GBM format documentation)
stem out - palette information consisting of
stem.0 : number of palette entries
stem.X.red : red value
stem.X.green: green value
stem.X.blue : blue value
X: Ranging from 1 to stem.0
Note: Not all palette entries must be
referenced by the bitmap data.
string in - the optional filetype extension reported
by GBM_Types to override autodetection
based on the file extension.
Return : "0", an error message or "ERROR" for an unknown error
Info : Reads the bitmap palette of the specified bitmap file.
Additional options (see GBM format documentation) may
be specified, e.g. "index=2".
Example :
/* Code in the procedure */
rc = GBM_FilePalette(filename, '', 'colors.')
if rc = "0" then
do
/* Print palette entries. Note the palette can be empty for true color bitmaps. */
say 'Number of palette entries: 'colors.0
say '----------------------'
do i = 1 to colors.0
say ' Index, (R,G,B): 'i', ('colors.i.red','colors.i.green','colors.i.blue')'
end
end
Function: GBM_FileData
Syntax : rc = GBM_FileData(filename, options, 'stem' [, fileExtension])
Params : string in - filename
string in - comma separated options
(see GBM format documentation)
stem out - The binary bitmap data. (No trailing dot!)
string in - the optional filetype extension reported
by GBM_Types to override autodetection
based on the file extension.
Return : "0", an error message or "ERROR" for an unknown error
Info : Reads the bitmap data of the specified bitmap file.
Additional options (see GBM format documentation) may
be specified, e.g. "index=2".
Example :
/* Code in the procedure */
rc = GBM_FileData(filename, '', 'data')
if rc = "0" then
do
expectedLength = (TRUNC((header.width * header.bpp + 31)/32)*4)*header.height
say ' Bitmap data length (expected): 'expectedLength
say ' Bitmap data length (read) : 'LENGTH(data)
end
Function: GBM_FileWrite
Syntax : rc = GBM_FileWrite(filename, options, 'stem1', 'stem2', 'stem3' [, fileExtension])
Params : string in - filename
string in - comma separated options
(see GBM format documentation)
stem1 in - header information consisting of
stem1.width : bitmap width
stem1.height: bitmap height
stem1.bpp : bitmap colour depth (bpp)
stem2 in - palette information consisting of
stem2.0 : number of palette entries
stem2.X.red : red value
stem2.X.green: green value
stem2.X.blue : blue value
X: Ranging from 1 to stem2.0
Note: The number of entries must match
stem1.bpp^2.
stem3 in - The binary bitmap data.
string in - the optional filetype extension reported
by GBM_Types to override autodetection
based on the file extension.
Return : "0", an error message or "ERROR" for an unknown error
Info : Writes a complete bitmap consisting of header, palette and data
to the specified file.
Additional options (see GBM format documentation) may
be specified, e.g. "compression=9" for PNG.
Example :
/* Code in the procedure */
rc = GBM_FileWrite('image.png', 'compression=9', 'header.', 'colors.', 'data')
if rc = "0" then
do
say 'SUCCESS'
end
Function: GBM_ScaleAlgorithms
Syntax : rc = GBM_ScaleAlgorithms('stem')
Params : stem out - supported scaling algorithms consisting of
stem.0 : number of algorithms
stem.X.algorithm : algorithm
X: Ranging from 1 to stem.0
Return : "0", an error message or "ERROR" for an unknown error
Info : Returns a list of all supported scaling algorithms.
Example :
/* Code in the procedure */
rc = GBM_ScaleAlgorithms('scaleAlgorithms.')
if rc = "0" then
do
say 'Number of supported algorithms: 'scaleAlgorithms.0
do i = 1 to scaleAlgorithms.0
say 'Algorithm: 'scaleAlgorithms.i.algorithm
end
end
Function: GBM_ScaleIsSupported
Syntax : rc = GBM_ScaleIsSupported(algorithm, bpp, 'stem')
Params : string in - scaling algorithm
(simple,nearestneighbor,bilinear,bell,bspline,mitchell,lanczos)
string in - bpp (bits per pixel) to test
stem in - palette information consisting of
stem2.0 : number of palette entries
stem2.X.red : red value
stem2.X.green: green value
stem2.X.blue : blue value
X: Ranging from 1 to stem.0
Note: The number of entries must match
bpp^2. For true color images it
can be 0.
Return : "0" (unsupported) or "1" (supported)
Info : Checks if a specific scaling algorithm is supporting
for the specified colour depth and palette.
Example :
/* Code in the procedure */
rc = GBM_ScaleIsSupported('lanczos', header.bpp, 'colors.')
if rc = "1" then
do
say 'Scaling is supported.'
end
Function: GBM_Scale
Syntax : rc = GBM_Scale(algorithm, 'stem1', 'stem2', 'stem3', 'stem4')
Params : string in - scaling algorithm
(simple,nearestneighbor,bilinear,bell,bspline,mitchell,lanczos)
stem1 in/out - header information consisting of
stem1.width : bitmap width
stem1.height: bitmap height
stem1.bpp : bitmap colour depth (bpp)
stem2 in/out - palette information consisting of
stem2.0 : number of palette entries
stem2.X.red : red value
stem2.X.green: green value
stem2.X.blue : blue value
X: Ranging from 1 to stem2.0
Note: The number of entries must match stem1.bpp^2.
stem3 in/out - The binary bitmap data.
stem4 in - destination size
stem.width : bitmap width
stem.height: bitmap height
Return : "0", an error message or "ERROR" for an unknown error
Info : Scales a bitmap using a user selectable algorithm.
The bitmap header, palette and data are modified and returned.
Example :
/* Code in the procedure */
newSize.width = header.width * 3
newSize.height = header.height * 3
rc = GBM_Scale('lanczos', 'header.', 'colors.', 'data', 'newSize.')
if rc = "0" then
do
say 'New width : 'header.width
say 'New height: 'header.height
end
Function: GBM_Reflect
Syntax : rc = GBM_Reflect(algorithm, 'stem1', 'stem2')
Params : string in - algorithm
(horizontal, vertical, transpose)
stem1 in/out - header information consisting of
stem1.width : bitmap width
stem1.height: bitmap height
stem1.bpp : bitmap colour depth (bpp)
stem2 in/out - The binary bitmap data.
Return : "0", an error message or "ERROR" for an unknown error
Info : Mirrors a bitmap using a user selectable algorithm.
The bitmap header and data are modified and returned.
Example :
/* Code in the procedure */
rc = GBM_Reflect('horizontal', 'header.', 'data')
if rc = "0" then
do
say 'SUCCESS'
end
Function: GBM_Rotate
Syntax : rc = GBM_Rotate(angle, 'stem1', 'stem2')
Params : string in - angle in degrees
(must be multiple of 90)
stem1 in/out - header information consisting of
stem1.width : bitmap width
stem1.height: bitmap height
stem1.bpp : bitmap colour depth (bpp)
stem2 in/out - The binary bitmap data.
Return : "0", an error message or "ERROR" for an unknown error
Info : Rotates a bitmap in increments of 90 or 180 degrees.
The bitmap header and data are modified and returned.
Example :
/* Code in the procedure */
rc = GBM_Rotate('90', 'header.', 'data')
if rc = "0" then
do
say 'SUCCESS'
end
Function: GBM_PaletteDataTo24bpp
Syntax : rc = GBM_PaletteDataTo24bpp('stem1', 'stem2', 'stem3')
Params : stem1 in/out - header information consisting of
stem1.width : bitmap width
stem1.height: bitmap height
stem1.bpp : bitmap colour depth (bpp)
stem2 in - palette information consisting of
stem2.0 : number of palette entries
stem2.X.red : red value
stem2.X.green: green value
stem2.X.blue : blue value
X: Ranging from 1 to stem2.0
Note: The number of entries must match stem1.bpp^2.
stem3 in/out - The binary bitmap data.
Return : "0", an error message or "ERROR" for an unknown error
Info : Upsamples a palette based bitmap to a 24bpp true colour bitmap.
The bitmap header and data are modified and returned.
Example :
/* Code in the procedure */
rc = GBM_PaletteDataTo24bpp('header.', 'colors.', 'data')
if rc = "0" then
do
say 'SUCCESS'
say 'New colour depth: 'header.bpp
end