Using GBMRX in your own REXX programs

Introduction

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.


GBMRX API function availability

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
1.10 GBM_ScaleAlgorithms
GBM_ScaleIsSupported
GBM_Scale
GBM_Reflect
GBM_Rotate
GBM_PaletteDataTo24bpp

GBMRX API Reference

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