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