Litestep: Image Extensions

Sidestep

Contents

Introduction
General
Image Definition
- new
- ~new
- reset
Drawing
- pixel
- line
- rect
- polygon
- ellipse
- arc
- composite
- text
Transformation
- scale
- rotate
- shear
- translate
- transform
Configuration
- smoothing
- scaling
Color Adjustment
- argb
- hsb
- contrast

Introduction

This build is based on Litestep 0.24.7 RC3, with the following changes:

ilmcut's fix for log line lengths. (link)
luthe's patch as from here, as discussed here
Andymon's tray service fix from xstep 0.24.7.1. (link)
Everything else that this readme describes.

There is only one new feature really—the ability to define images completely from the step.rc. An important side effect to this is the ability to provide color themes, without having to recreate every image in the new color. Taking advantage of the color theme features requires only slight modification to the step.rc for existing themes, but to really take advantage of it the way images are made needs to be rethought a bit. These new features are provided by Gdi+.

As a side effect of moving to Gdi+, bmp, png, jpeg, tiff, gif and emf/wmf files can all be loaded.

Obviously, everything that is new in this distribution calls out to be an image loading module. If and when Litestep gains this ability, I fully intend to turn this into such a module.

Installation

The easiest way to install is to overwrite the existing files in your Litestep directory with those from this distribution. Your system needs to have msvcp71.dll, msvcrt71.dll and gdiplus.dll available. If these are not available they copies should be obtained and placed into the same directory where you have installed Litestep. Gdiplus.dll, msvcp71.dll and msvcrt71.dll are available here.

Due to the changes this distribution is not dependent on zlib or libpng (zlib.dll, and libpng13.dll), however do not remove zlib.dll if you are using netloadmodule (if you're using OTS2 then you are using it, however if you don't know, don't remove it).

Examples

The examples folder contains several examples that are more hands on than this readme.

xLabel Alert

If you are loading an image with ".image=" in xlabel the name of the image must contain ".png" or ".bmp" (sans quotes). This is a limitation of xlabel and likely any xmodules that can load the associated icon of arbitrary path.

e.g.: MyLabelImage .image=.png_MyLabelBg

Contact

Please send any comments, suggestions and bug reports to hollow1@myrealbox.com.
Sidestep is availible for download from eric.redtetrahedron.org.

General

Actors

An image is defined as a list of Actors in the step.rc. Each Actor is a single line that begins with *Image. There is no limit, other than available memory, for the number of Actors in any image or the number of images. All of the available Actors are described below, in the Image Definition, Drawing, Transformation, Configuration and Color Adjustment sections.

Somethings to remember when creating images:

Colors can be specified in the hexadecimal form “RRGGBB” or as three decimal numbers, “R G B”. If you use three decimal numbers, they must be quoted.
The maximum line length in the step.rc is 4096 characters. In general this isn't an issue, but it might be in the Text and Polygon Actors.
In the below documentation, parameters that appear inside of [ ] are required; parameters that appear inside of ( ) are optional.
The origin is the upper left pixel and its coordinates are (0,0). The positive x-axis extends to the right, and the positive y-axis extends downward.
If a parameter is labeled “A real number” that parameter may have fractional parts. e.g. 3.2 Otherwise all numbers should be given as integers.

Inside an image definition two evars are set: $ImageWidth$ and $ImageHeight$. These are set to zero outside of an image definition. Remember that the bottom right pixel is $ImageWidth-1$, $ImageHeight-1$.

There are several Global Actors that can appear outside of image definitions. These include the Prefix Actors, the Postfix Actors and reset. Reset is the only Global Actor that cannot also be used within an image definition.

Prefix Actors

Prefix Actors are added to the beginning of the Actor list for any image that comes after them, until a reset or reset .prefix appears. These actors change how the following actors function in some way. The prefix actors are smoothing and scaling.

Postfix Actors

Postfix Actors are added at the end of the Actor list for any image that comes after them, until a reset or reset .postfix appears. These actors affect the output of all previous actors. The Postfix Actors are argb, hsb and contrast.

Errors

Whenever an error occurs it will be added to the Litestep log. The log can be enabled in the step.rc with the LSLogLevel n and LSLogFile file directives. Check the Litestep documentation for information about these directives. All Sidestep errors log at the error log level, n=1. It is highly advised that you enable the log while creating images even if you disable after you finish development.

Sidestep errors have the general form:

Litestep(Image): Description of error image_name(line received)

The image name and a copy of the line received are appended to the error to make tracking down and correcting the error easier. Note that any evars will have been expanded in the appened line. Following are a few examples of actual errors that may be reported.

Litestep(Image): Unknown command: "foo". test(*image foo 0 0 500 100 ffffff ffffff)

Litestep(Image): Invalid option. .png_scaling(*image scaling .biliner)

Litestep(Image): Invalid number of tokens. .png_scaling(*image composite 98 98 128 128 foo.png 0 0 32 32 Hi)

Image Definition

new

*Image new [name] [w] [h]
*Image new [image_name]

Both forms create a new image that can be loaded using the form .image=name.

The first actor creates a blank image with width, w and height, h. This image definition must be closed with a ~new actor. Prefix Actors are applied.

The second form is to import an image to the imaging system. Postfix actors are applied, and the image must be loaded using .image=image_name. This actor is designed to eliminate numerous definitions like the following, that do nothing but import an image for color themeing.

*Image hsb 0 -255 0
*Image new foo 700 40
*Image composite 0 0 $ImageWidth$ $ImageHeight$ foo.png
*Image ~new

All such definitions can be replaced with the much shorter and less image dependent code that follows, using the second form of the new actor.

*Image hsb 0 -255 0
*Image new foo.png

~new

*Image ~new

Closes an image opened with new and applies the global Postfix Actors.

Note: A ~new actor cannot be use with the *Image new [image_name] form of new. This will cause a parse error and subsequent images may not parse correctly.

reset

*Image reset (.prefix | .postfix)

Clears the current cache of Global Actors.

.prefix: (Optional) Clears all Prefix Actors.
.postfix: (Optional) Clears all Postfix Actors

When used without a parameter all global actors are cleared. This actor is only legal as a Global Actor, and cannot appear within an image definition.

Drawing

pixel

*Image pixel [x] [y] [color]

Colors a pixel.

x: The x coordinate of the pixel.
y: The y coordinate of the pixel.
color: The new color for the specified pixel.

line

*Image line [x1] [y1] [x2] [y2] [color]

Draws a line.

x1: The x coordinate of the starting point of the line.
y1: The y coordinate of the starting point of the line.
x2: The x coordinate of the end point of the line.
y2: The y coordinate of the end point of the line.
color: The color of the line

This actor is affected by the current smoothing mode.

rect

*Image rect [x] [y] [w] [h] [color] (fill_color)

Draws a rectangle.

x: The x coordinate of the upper left corner of the rectangle.
y: The y coordinate of the upper left corner of the rectangle.
w: The width of the rectangle.
h: The height of the rectangle.
color: The color of the 1 pixel wide outline of the rectangle.
fill_color: (Optional) The color the rectangle is filled with.

This actor is affected by the current smoothing mode.

polygon

*Image polygon [x1] [y1] [x2] [y2] [x3] [y3] (x4 y4 ... xn yn) [color] (fill_color)

Draws a closed polygon.

x1: The x coordinate of the first vertex.
y1: The y coordinate of the first vertex.
x2: The x coordinate of the second vertex.
y2: The y coordinate of the second vertex.
x3: The x coordinate of the third vertex.
y3: The y coordinate of the third vertex.
x4 y4 ... xn yn: (Optional) The x and y coordinates of the remaining vertices in the polygon.
color: The color of the 1 pixel border around the polygon.
fill_color: (Optional) The color the polygon is filled with.

The polygon may intersect with itself. This actors is affected by the current smoothing mode.

Note: Polygons are currently limited to 127 sides.

ellipse

*Image ellipse [x] [y] [w] [h] [color] (fill_color)

Draws an ellipse.

x: The x coordinate of the upper left corner of the bounding box for the ellipse.
y: The y coordinate of the upper left corner of the bounding box for the ellipse.
w: The width of the ellipse.
h: The height of the ellipse.
color: The color of the 1 pixel wide outline of the ellipse.
fill_color: (Optional) The color the ellipse is filled with.

This actor is affected by the current smoothing mode.

arc

*Image arc [x] [y] [w] [h] [sa] [swa] [color] (fill_color)

Draws an arc. The arc is part of an ellipse.

x: The x coordinate of the upper left corner of the bounding box for the ellipse that contains the arc.
y: The y coordinate of the upper left corner of the bounding box for the ellipse that contains the arc.
w: The width of the ellipse that contains the arc.
h: The height of the ellipse that contains the arc.
sa: The angle between the positive x-axis and the start of the arc. A real number.
swa: The angle between the starting and ending points of the arc. A real number.
color: The color of the 1 pixel wide outline of the arc. The outline only covers the curve of the arc.
fill_color: (Optional) The color the arc is filled with.

This actor is affected by the current smoothing mode.

composite

*Image composite [dx] [dy] [dw] [dh] [image] ([sx] [sy] [sw] [sh])

Composites an image with the current image.

dx: The x coordinate of the upper left corner of the destination rectangle.
dy: The y coordinate of the upper left corner of the destination rectangle.
dw: The width of the destination rectangle.
dh: The height of the destination rectangle.
image: The image to composite. If the image is a difference size than the destination rectangle, it will be scaled to fit. Any image that Litestep can load, with the exception of merged images using |, can be loaded.
sx: (Optional) The x coordinate of the upper left corner of the source rectangle.
sy: (Optional) The y coordinate of the upper left corner of the source rectangle.
sw: (Optional) The width of the source rectangle.
sh: (Optional) The height of the source rectangle.

The optional source parameters can be used to specify a subsection of an image to composite. If any of the source coordinates are given, they all must be given.

This actor is affected by the current scaling mode.

Icons are handled properly, including Windows XP icons (32bit icons). This includes selection of a subsection of an icon to composite and smoothed scaling (when enabled).

An image may not be composited with itself or any image that contains it. The offending composites will be removed as they are found, and an error message will be posted to the Litestep log.

For example:

;Error, cannot composite oneself.
*Image new foo 50 50
*Image composite 0 0 49 49 .image=foo
*Image ~new

;Error, cannot indirectly composite oneself.
*Image new bar 50 50
*Image composite 0 0 49 49 .image=spoon
*Image ~new

*Image new spoon 50 50
*Image composite 0 0 49 49 .image=bar
*Image ~new

text

*Image text [font] [size](px|pt) (.bold | .italic | .underline | .strikeout) [x] [y] [color] [text]

Writes the given text to the image

font: The font to use. If the font name is more than one word (such as ”Courier New“), it must be quoted.
size: The font size to use. Optionally, px or pt can be appended to the size, indicating that the size is in pixels or points, respectively. The default is pixels.
.bold, .italic, .underline, .strikeout: (Optional) Style modifiers to use. They may appear in any order or combination, or be absent altogether.
x: The x coordinate of the upper left corner of the starting point for the text.
y: The y coordinate of the upper left corner of the starting point for the text.
color: The color to use for the text.
text: The text to write.

Not all font types are supported. Specifically, .fon will not work. These are limitations of Gdi+ which is used to render the text. In the event that the specifed font cannot be used the system sans serif font will be used.

Transformation

scale

*Image scale [sx] [sy] (.set)
*Image scale [sxy] (.set)

Scales all subsequent actions on the image, relative to the origin.

sx: The scaling factor in the x direction. A real number.
sy: The scaling factor in the y direction. A real number
sxy: The scaling factor for uniform scaling in both directions. A real number.
.set: (Optional) Indicates that the transformation should be set to only this transformation rather than the default of performing this transformation after all earlier transformation actors have been applied.

This actor is equivalent to: *Image transform sx 0 0 sy 0 0, as such the scaling factor cannot be zero.

rotate

*Image rotate [angle] (.set)

Rotates all subsequent actions on the image, relative to the origin.

angle: The angle to rotate the image, in degrees. A real number
.set: (Optional) Indicates that the transformation should be set to only this transformation rather than the default of performing this transformation after all earlier transformation actors have been applied.

The angle is measured from the positive x-axis rotating toward the positive y-axis. This Actor is equivalent to: *Image transform cos(angle) -sin(angle) sin(angle) cos(angle) 0 0.

shear

*Image shear [sx] [sy] (.set)

Shears all subsequent actions on the image.

sx: The magnitude of the shear in the x direction. A real number.
sy: The magnitude of the shear in the y direction. A real number
.set: (Optional) Indicates that the transformation should be set to only this transformation rather than the default of performing this transformation after all earlier transformation actors have been applied.

This actor is equivalent to: *Image transform 1 sx sy 1 0 0.

translate

*Image translate [dx] [dy] (.set)

Translates all subsequent actions on the image.

dx: Number of pixels to translate in the x direction.
dy: Number of pixels to translate in the y direction.
.set: (Optional) Indicates that the transformation should be set to only this transformation rather than the default of performing this transformation after all earlier transformation actors have been applied.

This actor is equivalent to: *Image transform 1 0 0 1 dx dy.

transform

*Image transform [m11] [m12] [m21] [m22] [dx] [dy] (.set)

Arbitrarily transforms all subsequent actions on the image.

m11: The value is the 1st row, 1st column of the transformation matrix. A real number.
m12: The value is the 1st row, 2nd column of the transformation matrix. A real number.
m21: The value is the 2nd row, 1st column of the transformation matrix. A real number.
m22: The value is the 2nd row, 2nd column of the transformation matrix. A real number.
dx: The number of pixels to translate in the x direction.
dy: The number of pixels to translate in the y direction.
.set: (Optional) Indicates that the transformation should be set to only this transformation rather than the default of performing this transformation after all earlier transformation actors have been applied.

When used as shown in the following example, this actor can be used to reset (to no transformation) the transformations applied to the image.

*Image transform 1 0 0 1 0 0 .set

When .set is not used the transformation matrices are multiplied CN where C is the current transformation matrix and N is the matrix defined by this actor. (this is true all transformation actors.) The transformation is carried out as the following. The first two values in the resulting vector are the new x and y coordinates.

	m11		m12		dx				x
	m21		m22		dy				y
	0		0		1				1

Configuration

smoothing

*Image smoothing [.none | .antialias]

Changes the smoothing mode.

.none: The default smoothing mode.
.antialias: Smoothed lines

This actor is a Prefix Actor.

scaling

*Image scaling [.std | .bilinear | .bicubic | .nearestneighbor]

Changes the scaling mode.

.std: The default scaling mode.
.bilinear: Bilinear scaling
.bicubic: Bicubic scaling
nearestneighbor: Nearest neighbor scaling. This method is also known as pixel doubling. (no interpolation)

This actor is a Prefix Actor.

Color Adjustment

argb

*Image argb [da] [dr] [dg] [db]
*Image argb [color]

Adjusts the image colors in the ARGB colorspace.

da: The change in the alpha channel. Must be between -255 and 255, integer values only.
dr: The change in the red channel. Must be between -255 and 255, integer values only.
dg: The change in the green channel. Must be between -255 and 255, integer values only.
db: The change in the blue channel. Must be between -255 and 255, integer values only.
color: A rgb color specification that contains the red, green and blue colors to adjust by. Note: This form of the actor can only adjust in the positive direction.

The new color will be a+da, r+dr, g+dg and b+db. If the new value for any channel is outside of 0 to 255, it will be replaced with 0 or 255 respectively.

If all parameters are 0, the actor will be ignored and a warning will be placed in the Litestep log.

This actor is a Postfix Actor.

hsb

*Image hsb [dh] [ds] [db]

Adjusts within the HSB colorspace.

dh: The change in hue. Must be between -360 and 360, integer values only.
ds: The change in saturation. Must be between -255 and 255, integer values only.
db: The change in brightness (value). Must be between -255 and 255, integer values only.

This conversion is lossy. The internal image format uses the ARGB colorspace and conversion to HSB and back will result in a slightly different image. The saturation and brightness are clamped to 0 to 255; the hue results in a valid transformation at all times.

If all parameters are 0, the actor will be ignored and a warning will be placed in the Litestep log.

This actor is a Postfix Actor.

contrast

*Image contrast [dc]

Adjusts the contrast of the image.

dc: The change in contrast. Must be between -255 and 255, integer values only.

If dc is 0, the actor will be ignored and a warning will be placed in the Litestep log.

This actor is a Postfix Actor.