# 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