RxImgSze: Raster Image Support for REXX

RxImgSze

RxImgSze: Raster Image Support for Rexx

Copyright © 2013-2014, Jan-Erik Lärka

http://www.xn-lrka-loa.com/

Raster image libraries, code and routines from
Generalized Bitmap Module (GBM),
currently maintained by Heiko Nitzsche, Germany.

http://heikon.home.tlink.de/

License agreement

License agreement

Copyright © 2013-2014, Jan-Erik Lärka
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of "Jan-Erik Lärka" nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Installation

Installation


Unpack files and place the .dll file in C:\ecs\dll or C:\OS2\DLL and this help file in C:\ecs\book or C:\OS2\BOOK

Introduction to REXX

Introduction to REXX

REXX extend what you can do with your computer.

Classic REXX that ship with eComStation and OS/2 allow you to write straight forward code in english with few obstacles as rules formatting requirements that may exist in other similar languages.

The REXX language allow for various programming styles depending on your personal preference, which may confuse, but also allow you to explore it and try more.

Absolute beginners to REXX programming should read one of the REXX introduction tutorials available.

You can with relatively little knowledge extend REXX if it doesn't contain all the components you need. This library is an example of how you can add functionallity to extend REXX beyond the original implementation.

Help to write REXX code

Help to write REXX code


You can write REXX code with a plain Text Editor

Editors with support for programming lanuages usually contain various functions to highlight different parts of the code to inform you about various aspects of the code and help you understand it better.

Example of Syntax Highlightning
/*
  * Filename: Example.cmd
  * Author: JAN-ERIK
  * Created: Sat Mar 22 2014
  * Purpose: Introductional example script to REXX
  * Changes:
  */

SAY "Example of Syntax highlightning"  

Examples of Text Editors with Syntax Highlightning

EPM (Enhanced Editor)

FTE (Folding Text Editor)

EPM (Enhanced Editor)

EPM (Enhanced Editor)

EPM (Enhanced Editor) that ships with OS/2 and eComstation is very powerful and support various progamming languages, not only REXX. EPM may not look that powerful at a first glance if you haven't tried it out before. You can however add buttons to the buttonbar of the EPM that add support for syntax highlightning with little effort.
 
Buttonbar: Right click
Select: Buffet
Window: Toolbar customization
Area: Buffet toolbar:
Click: > (Right most button)
Button: [  KwdHilit  ]
Drag & Drop¹: KwdHilit
Target: Current toolbar:
Button: [ OK ]
Window: EPM main window
Buttonbar: Right click
Menu: Save as...
Window: Save Toolbar
Field: Enter a name for the toolbar.
Type: Highlight
Window: EPM main window
Menu: Options → Preferences → Settings...
Window: Settings
Tab: Toolbars
Grouping area: Toolbars
Dropdown: Highlight
Button: [ Make current ]
Close window: Settings

¹) Drag & Drop with the Right Mouse Button

FTE (Folding Text Editor)

FTE (Folding Text Editor)

Various versions of FTE (Folding Text Editor) exist on the internet and they provide good support for REXX.

Syntax Highlightning, automatic Indention to ease reading and debuggning of code, menus to insert comments and useful commands within the languages make FTE very useful.

Note

A drawback with some versions of FTE is that the folding of END in DO-END pair sections loose track of position and in default configuration with OS/2 version doesn't line up right below DO.

IF ARG ( 1 ) = 1 THEN
DO
    SAY 'Please wait...'
    CALL SysSleep 10
    END

instead of

IF ARG ( 1 ) = 1 THEN
DO
    SAY 'Please wait...'
    CALL SysSleep 10
END

Internet resources for FTE (Folding Text Editor):

http://www.os2site.com/sw/apps/editors/fte/index.html
http://hobbes.nmsu.edu/h-search.php?key=FTE+Editor&pushbutton=Search

Introduction to RxImgSze

Introduction to RxImgSze


The design of external function packages allow the programmer to add code to dynamically handle various needs in just i functions. This has been explored as much as possible in this library and require you as a reader to pay attention to the subtle differences between the provided examples.  

Library functions
rxImgLoadFuncs - Load all other functions in the library
rxImgDropFuncs - Unload all other functions in the library
rxImgVersion - Show information for this library
rxImgReSize - Resize and reduce/increase colors in image
rxImgCapture - Capture image

rxImgLoadFuncs

rxImgLoadFuncs
    
Syntax:            CALL rxImgLoadFuncs
Parameter(s) Returns/Note


none empty string


Purpose: Load all functions for usage so that they are available in the REXX script

Example
CALL RxFuncAdd 'rxImgLoadFuncs', 'rxImgSze', 'rxImgLoadFuncs'
CALL rxImgLoadFuncs

rxImgDropFuncs

rxImgDropFuncs
   
Syntax:            CALL rxImgDropFuncs
Parameter(s) Returns/Note


none empty string


Purpose: Unload all previously loaded functions when done

rxImgVersion

rxImgVersion

Syntax:            result = rxImgVersion( [information] )
Parameter(s) Returns/Note


information (Optional)
none  "rxImgSize: version 1.03, GBM: version 1.12"
"RxImageSize"  "1.03"
"GBM"  "1.12"
"Filters" "nearestneighbor, bilinear, bell, bspline, ..."
"Palettes" "BW, VGA, 8B, 4G, 7x8x4, 6x6x6, 4x4x4, ..."
"Extra" "ASPECT, ERRDIFF, HALFTONE"


Purpose: Return information about this library and capabilities.


Note: Only the first letter (if any) has to be specified.

Example 1
SAY rxImgVersion()
Purpose: Get general information


Output: rxImgSize: version 1.03, GBM: version 1.12

Example 2
SAY rxImgVersion( 'R' )
Purpose: Get information about the rexx library


Output: 1.03

rxImgReSize

rxImgReSize

Syntax:            result = rxImgReSize( input_image[, output_image, [width], [height], [options][, palette_file] ] )
Parameter(s) Return/Note


input_image (Mandatory)
none "Syntax: rc = rxImgReSize( Source_path_and_filename..."
"C:\nofile.xyz" "2"
"C:\GMARBLE.BMP" "179 179 8" A valid filename and no other parameters


output_image (Optional)
none Will use the input file for output e.g. overwrite it.
"C:\nofile.xyz" "11" for unknown filetype etc.
"C:\OUT.BMP" Will write the file if it's a valid image format


width (Optional)
none keep width (unless ASPECT in parameter options)
120 Resize image to 120 pixels wide


height (Optional)
none keep height (unless ASPECT in parameter options)
120 Resize image to 120 pixels high


options (Optional)
none -
"nearestneighbor" Use the filter nearestneighbor during resize
"7x8x4" See Palettes
"1bpp" See also the parameter palette_file below
"ASPECT" See Aspect
"ERRDIFF" See Extra
"HALFTONE" See Extra


palette_file (Required only with option 1bpp, 4bpp & 8bpp)
"C:\PaletteFile.xyz" -


Purpose: Copy and/or resize image, reduce or increase colors of image


Note: A return value of 0 indicate "no problem" while other integer

values indicate various problems depending on input


Extra note:
 Pay attention to the special case when you only provide the path

and file name to a valid image. The return value is then

width height color_depth

Example 1
SAY rxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" )
Purpose: Get information about width, height and color depth of image


Output: 179 179 8

Example 2
SAY RxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE.GIF" )
Purpose: Copy image and save the converted image as GIF


Output: 0

Example 3
SAY RxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE.GIF" , 120 )
Purpose: Copy image, resize width to 120 pixels and keep height

Save the converted image as GIF


Output: 0

Example 4
SAY RxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE.JPG" ,,  150 )
Purpose: Copy image, resize height to 150 pixels high and keep width

Save the converted image as JPG


Output: 0

Example 5
SAY rxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE.PNG" ,, 200 , "ASPECT" )
Purpose: Copy image, resize to 200 pixels high but keep aspect ratio between width and height

Save the converted image as PNG


Output: 0

Example 6
SAY rxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE2.GIF" , 80 ,, "GAUSSIAN 6x6x6 ERRDIFF" )


Purpose: Copy image, resize width to 80 pixels wide but keep height

Use Gaussian filter during quality scale, reduce the colors with

palette 6x6x6 and error diffusion and save the converted image as GIF


Output: 0

Example 7
SAY rxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE2.BMP", 350 ,, "ASPECT 256" )
Purpose: Copy image, resize width to 350 pixels wide and keep aspect ratio between width and height

Reduce colors to maxium of 256 colors and save the converted image as BMP


Output: 0

Example 8
SAY rxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE2.PNG" ,, 500, "HALFTONE KAISER RGB" )
Purpose: Copy image, resize width to 500 pixels and keep height

Use Kaiser filter during halftone quality scale and save the converted image as PNG


Output: 0

Example 9
SAY rxImgReSize( "C:\OS2\BITMAP\GMARBLE.BMP" , "C:\GMARBLE3.BMP" ,, 250, "4bpp", "C:\Palfile.xyz" )
Purpose: Copy image, resize height to 250 pixels and keep width

Reduce colors to 4 bit (16 colors) with the use of a palette file and save the converted image as BMP


Output: 0

rxImgCapture

rxImgCapture

Syntax:            result = rxImgCapture( window_name[, left_coordinate[, bottom_coordinate[, right_coordinate[, top_coordinate[, save_as_path_and_filename ] ] ] ] ] )    
                          result = rxImgCapture( window_name[, "INTERIOR"/"WINDOW"][, left_coordinate[, bottom_coordinate[, right_coordinate[, top_coordinate[, save_as_path_and_filename ] ] ] ] ] )    
                          result = rxImgCapture( window_name[, "INTERIOR"/"WINDOW"][, save_as_path_and_filename ] )
Parameter(s) Return/Note


window_name (Mandatory)
none "22"
"DESKTOP" "0"
"Editor" Will capture a window with the title name "Editor" or

if none with just that name a window that contain the text "Editor" in the title


"INTERIOR" (Optional)
"INTERIOR" Will capture the interior of the window instead of the full frame
"WINDOW" Will capture the whole size of the window (default)


left_coordinate (Optional)
none start 0 pixels in of specified window
10l start 10 pixles from left of specified window
10x start 10 pixels from left of specified window
10% start 10% in from the left of specified window (parameter position is important)


bottom_coordinate (Optional)
none start 0 pixels in of specified window
12b start 12 pixles from bottom of specified window
12x start 12 pixels from bottom of specified window
12% start 12% in from the bottom of specified window (parameter position is important)


right_coordinate (Optional)
none start 0 pixels in of specified window
14r start 14 pixles from right of specified window
14w 14 pixels wide image
14% 14% wide image of specified window (parameter position is important)


top_coordinate (Optional)
none start 0 pixels in of specified window
16t start 16 pixles from top of specified window
16h 16 pixels high image
16% 16% high image of specified window (parameter position is important)


save_as_path_filename (Optional)
none defaults to "temporary.bmp" in the current directory
"C:\Captured.PNG" Saves the captured image as Captured.PNG in C:


Purpose: Capture whole or part of the screen and save as image


Note: This function is very "dynamic" and only the first and last parameter has fixed positions.

Example 1
SAY rxImgCapture( "DESKTOP" )
Purpose: Capture the whole desktop and save as "temporary.bmp" in the current folder


Output: 0

Example 2
SAY rxImgCapture( "DESKTOP" , "100b" , "50x" , "50%" , "C:\Capture1.bmp" )
Purpose: Capture parts of the desktop and mix values, save to "C:\Capture1.bmp"


Output: 0

Example 3
SAY rxImgCapture( "Firefox" , "interior" , "150t" , "C:\Firefox.png" )
Purpose: Capture interior of window that contain the name Firefox,

avoid the toolbar buttons at the top and save to "C:\Firefox.png"


Output: 0