GBMRX has a simple and straightforward API consisting of 12 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:
GBMRX Version | API function name |
---|---|
1.00 | GBM_LoadFuncs GBM_DropFuncs GBM_Version GBM_VersionRexx GBM_Types GBM_IsBppSupported GBM_FileType GBM_FilePages GBM_FileHeader GBM_FilePalette GBM_FileData GBM_FileWrite |
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