Graphics Functions Graphics FunctionsArtWonk has both Graphics modules for quick and easy graphics drawing, and Function module Graphics Functions for both drawing and image processing.
ArtWonk graphics involves three separate elements, the Frame, which holds the image; the Picture, which is the graphics display of the image in the frame; and the Bitmap which hold the full color image memory. For an in depth discussion of Frame, Picture, and Bitmap see the Graphics module page.
An important feature of graphics functions is the ability to have multiple Pictures/Bitmaps, up to 128. This provides an especially powerful tool for algorithmic paint effects because you can pre load several bitmaps then combine them interactively into the final composite image.
However the bitmap number is an optional parameter in most functions, defaulting to the same bitmap #0 ("bmp=0") used by the Graphics modules, so until you need them you can safely ignore them.
RGB converts separate 0-255 color components for red, green and blue into the single 24 bit color value used by most graphics functions. The pRed, pGreen and pBlue functions deconstruct a 24 bit color value into the 0-255 color component.
SetSym1 (X,Y, Width, Height[, oX=0, oY=0]) Produces an 8 element array of symmetries about the X,Y point within the area given by Width, Height. Optionally offset by oX and oY. Use S1X, S2X to access the points to draw with symmetry.
SetSym1 (X,Y, Width, Height[, oX=0, oY=0]) - Identical to SetSym1. Two arrays are available to use with line endpoints. For more complex Symmetry such as polygon vertices or symmetry within symmetry use the global arrays to store the symmetries as sub arrays.
S1X(N) ~ (Also S1Y, S2X, S2Y) Return symmetry value from symmetry array, at symmetry setting N.
Symmetry settings for N are:
0 = original point
1 = reflect for 2-way
2, 3 = swap X's & Y's for 4-way
4-7 = 8-way
Prototypes for Graphics Utilities
RGB ( Red, Green, Blue) ~ Returns the 24 bit integer from the RGB components.
pRed(Color) ~ Returns the red part of a 24 bit RGB color integer.
pGreen(Color) ~ Returns the green part of a 24 bit RGB color integer.
pBlue(Color) ~ Returns the blue part of a 24 bit RGB color integer.
GetImageWidth(N=0) ~ Returns the width of image bitmap N in pixels.
GetImageHeight(N=0) ~ Returns the height of image bitmap N in pixels.
GetFrameWidth() ~ Returns the width of the image frame in pixels.
GetFrameHeight() ~ Returns the height of the image frame in pixels.
GetScreenWidth() ~ Returns the width of the monitor screen in pixels.
GetScreenHeight() ~ Returns the height of the monitor screen in pixels.
SetSym1(X,Y, Width, Height, [ oX=0, oY=0]) ~ Create symmetry array #1
SetSym2(X,Y, Width, Height, [ oX=0, oY=0]) ~ Create symmetry array #2
S1X(N) ~ Return X point from symmetry array #1 at symmetry N (0-7)
S1Y(N) ~ Return Y point from symmetry array #1 at symmetry N (0-7)
S2X(N) ~ Return X point from symmetry array #2 at symmetry N (0-7)
S2Y(N) ~ Return Y point from symmetry array #2 at symmetry N (0-7)
BoxWithin(left, top, width, height, tleft, ttop, twidth, theight) ~ true if
box is within target box
Functions for using the mouse to interact with the graphics Picture.
Prototypes for Graphics Mouse
SetMouse(Flag) ~ Disables graphics popup menues & move if NZ
GetMouseX() ~ Returns mouse x position in pixels
GetMouseY() ~ Returns mouse y position in pixels
GetMouseShift() ~ Returns mouse shift flag on mouse down or move
GetMouseButton() ~ Returns mouse button on mouse down or move
Image files can be loaded and saved with the LoadPic and SavePic modules or with the these functions. The main difference is the function versions of load and save provide automatic appending of serialization numbers to the name, by giving a num parameter of 0 or greater.
Only the name parameter is required, all other parameters are optional and default to most commonly used values:
name is a string parameter (it must be in quotes) that specifies the file name. If you format the name parameter so that it contains a full path+name+ext (the test is to see if a ":" is the 2nd character in the name), then the name is used as the full path name, ignoring the other name parameters.
num is a number appended to the name, default is -1, no number appended.
ext is the extension parameter, defaulting to ".bmp" can also use .jpg, .png, .gif, etc.
path is the file path such as "c:\My Pictures\animations\" - if the path is empty (the default) or the file cannot be found in the path given, ArtWonk will use the same path as last used to load or save the Patch file.
bm is the bitmap number, and as usual it defaults to bitmap #0. Note that LoadImage loads the image to the Bitmap and automatically copies it to the Picture, so it is immediately displayed; however SaveBitmap only saves what is in the given Bitmap, which may or may not differ with what is displayed in the Picture.
Image Tiles
ArtWonk includes a tiling engine that will merge image tiles with the composit display image. Tile source images are stored in up to 128 Pictures, numbered 0-127 and defaulting to 0, just as other images, however they are a different set of Pictures. Thus, you can load an image into the default bmp=0, and you can load a tile source image into the default tpic=0, and they will be in different places. Tile source pictures assume a .bmp image format, so there is no ext parameter.
Any .bmp image can be a tile source, whether is was an image built with ArtWonk or from some other source. What defines a Tile source image is 1. it resides in a tile picture buffer (tpic), and 2. it has an associated tile grid set for it.
Use SetTileGrid to define the tile grid for subsequent tile operations. All parameters are optional. The number of columns, or vertical strips, is set by cols, which must be 1 or greater; the number of rows, or horizontal strips, is set by rows, which also must be 1 or greater. ArtWonk will "score" the tile source image into the grid specified; pixels that do not evenly divide are effectively "trimmed" at the right for columns, and the bottom for rows.
Most tiling functions take a tile number, which is the 0 based count of tiles, left to right, top to bottom. So if you set a grid of 3 columns by 4 rows, the top right tile would be tile number 2, the bottom left tile would be 9, and the bottom right tile would be 11.
Prototypes for Graphics File Load & Save
LoadImage("name", num=-1, "ext"="bmp", "path"="",
bm=0) ~ Load from file
SaveBitmap("name", num=-1, "ext"="bmp", "path"="",
bm=0) ~ Save bitmap to a file
LoadTilePicture("name", num=-1, "path"=""', tpic=0)
~ Load tile source picture from .bmp file
SetTileGrid(cols=1, rows=1, tpic=0) ~ set a uniform matrix of picture cells
GetTileWidth(tpic=0) ~ Return width of tile in pixels
GetTileHeight(tpic=0) ~ Return height of tile in pixels
MatchingFiles("path"="", "name"="",
"ext"="") ~ Return number of matching files
When using bitmap functions, keep in mind that Bitmap, Image, and Frame are different components of the final picture. Bitmap is the memory array where the 24-bit image pixels are stored, Picture is the divice dependent display memory, usually residing in the video card, and Frame is the Windows object that holds the viewable picture, which in ArtWonk you display by selecting the main menu Options/Graphics.
ArtWonk has a single Frame and Picture, but can have up to 128Bitmaps, numbered 0 to 127. Except for default bitmap, 0 (bm=0), bitmaps must be created to dimension the computer memory to hold them. This is automatic when loading an image (LoadBitmap), or copying to a bitmap (CopyBitmapToBitmap).
Prototypes for Graphics Bitmap
CreateBitmap(w,h,color,bm=0) ~ Create new blank image buffer
CropImage(left, top, width, height,bm=0) ~ Crop image
AdustFrameToBitmap(bm=0) ~ Frame is resized to bitmap
CopyBitmapToBitmap(src, dst=0) ~ Copy a bitmap from source to destination
CombinePictureAndBitmap(bm=0) ~ Full merge of picture with bitmap, makes both
same
CopyBitmapToPicture(bm=0) ~ Full copy of bitmap to picture, replaces previous
picture
CopyPictureToTilegrid(bm=0, tpic=0) ~ Full copy of picture to tilegrid, replaces
previous tilegrid
ResizeImage(width, height,qual=2,bm=0) ~ Higher quality means slower speed.
Qual: 1 to 3
TileImage(width, height,bm=0) ~ Tile image - step & repeat image to width,
height given
EraseImage(bm=0, color=0) ~ Clears bitmap & picture
SetPixel(x, y, color, bm=0) ~ Set pixel in bitmap only, not in picture
GetPixel(x, y, color, bm=0) ~ Returns color of pixel in bitmap
SetModuleBitmap(bm=0) ~ Set bitmap to be used by graphics
modules
Merge provides exceptional control over image merging and the superimposition of multiple images.
Merge functions (as well as Image Processing functions) can affect the entire image, or only a portion of it, as set by AreaOn; when using an Area, keep in mind that the area specified is always the area of the destination image, not the source.
Merge functions may be set to be a simple copy operation (MergeOff) or it can be set to complex merges (MergeOn), similar to alpha blending but considerably more powerful and flexible.
MergeOn parameters (all optional):
resize - 0 = no resizing, the merge image is cropped to the size of the existing Bitmap or to the area specified by AreaOn. NZ = resize, the merge image is resized to the size of the Bitmap or to the area specified by AreaOn.
tcol - Transparent color. Set to -1 for no transparancy, otherwise set to the color that should be considered transparent. The transparent color is not copied from the source image.
mode - sets how the merge will occur. There are 14 merge modes:
PctHi, PctLo - Merge amount parameters in percent (0-100). See above modes for usage.
bm - the bitmap number of the destination image, which should be same as the AreaOn bm setting.
Prototypes for Graphics Merging
AreaOn(left, top, width, height,bm=0) ~ Sets merge target area
AreaOff(bm=0) ~ Use entire image as merge target
AreaDup(src, dst) ~ Duplicate an existing Area setting from another bitmap
MergeOn(resize=0, tcol=0, mode=1, PctHi=50,PctLo=0, bm=0) ~ See documentation
MergeOff(bm=0) ~ Use simple replacement instead of merge
MergePicture(src, bm=0) ~ Merge source picture with image
MergeBitmap(src, bm=0) ~ Merge source bitmap with image
MergeTile(tile=0, tpic=0, bm=0) ~ Merge source tile with image
MergeTileTo(x,y,tile=0, tpic=0, bm=0) ~ Merge source tile with image
LoadTileGrid(cols=10, rows=10, "path"="", "name"="",
"ext"="", width=0, height= 0, bm=0, tpic=0) ~ Loads given
tile grid with image files from directory, then copies it to the given bitmap.
If width is <=0 then the current Frame width is used, if height is <=
0 then the height is automatically adjusted according to the aspect ratio of
the first tile image. If "ext" is blank (default) all files types
in directory will load; name specifies the first characters of the file name
and is formatted as "name*" - leave blank (defalut) to load all filenames.
Returns max number of tiles loaded into the tile grid.
CreateRegion specifies a non rectangular region for Image Processing and Sprites (Note: the Image Processing region can be specified by Area or Region, the Merge region is specified by Area, and the Sprite region is specified by Region.)
Since the region is defined like a polyline of up to a maximum of 32767 points (and in fact you can use the DrawPolyLine function to visualize a region before creating it), the CreateRegion function uses two arrays to define the points. These are standard global arrays (0-999) as used by the array functions and modules.
CreateSprite converts the current Region into a graphics sprite object that may be animated.
Prototypes for Graphics Region
CreateRegion(N,Ax,Ay, Ox=0,Oy=0, bm=0) ~ N=number of points; Ax, Ay; offset
Ox,Oy
RegionOn(bm=0) ~ Use Region as image processing target
RegionOff(bm=0) ~ Use Area or entire image as image processing target
GetRegionWidth(bm=0) ~ Returns width of current Region, 0 if none defined
GetRegionHeight(bm=0) ~ Returns height of current Region, 0 if none defined
CreateSprite(bm=0) ~ Create a sprite from the current Region
DeleteSprite(bm=0) ~ Delete currently defined sprite
PasteSprite(x,y bm=0) ~ Paste the current sprite into the image.
MoveSprite(x,y bm=0) ~ Move the current sprite to a new position within the
image.
ArtWonk includes a rich set of Image Processing functions. When using Image Processing, keep in mind that these functions work on the Bitmap, which is an large array of memory representing the image pixels. Therefore many image processing functions are slow, especially when using larger images. Care should be used when image processing in real time, especially if MIDI music is also being generated. Often it will be better to do the image processing as a setup, prior to running the animation or the MIDI music.
You can stack image processing functions as deeply as you like, however normally after an image processing function is completed the image will display (paint). If you are stacking image processing, you can save a great deal of cpu overhead as well as maintain better control over image display by using InhibitPaint and AllowPaint. Keep in mind that once InhibitPaint is called for a particular bitmap, no image will be displayed until AllowPaint is called. Although only bitmap 0 will be visually affected, as it is the display bitmap, a non visible Picture is maintained with all the other Bitmaps, so it is a good idea to use InhibitPaint even with non visible bitmaps when stacking image processing functions.
Most of the Image Processing functions are very easy to use. The exception is the powerful MatrixConv(vAry,div,ints,ofst=0,bm=0) function, which provides a means to create custom convolution filters. The parameters for this function are:
vAry - is an 9 element array (0-8) of values from -32767 to 32767 that determins the 3x3 pixel processing grid. This is the same global array (0-999) as used by the array functions and modules. Here is an array that will produce a sharpen filter:
vAry(0) = -1
vAry(1) = -1
vAry(2) = -1
vAry(3) = -1
vAry(4) = 9
vAry(5) = -1
vAry(6) = -1
vAry(7) = -1
vAry(8) = -1The convolution matrix filter alters each pixel's color based on its current color and the colors of any neighboring pixels. The array of filter matrix values are coefficients. When a pixel is processed, its color value is multiplied by the coefficient in the array's center and any pixels within the 3x3 grid are multiplied by the corresponding coefficients in the array. The sum of the products becomes the target pixel's new value.
div - the divisor of the matrix filter values. Valid values are -999 to 999. The divisor is the coefficient denominator. Each coefficient in the filter matrix is divided by the divisor before being applied to a pixel.
inits - the intensity of the matrix filter. Valid values are 0 to 255. The intensity is added to the product of the matrix calculation and the divisor to shift the value of each pixel by a fixed amount.
ofst - the address offset in the value array for the 9 matrix elements. This allows you to have multiple 9-element matrix arrays in a single ArtWonk value array, and just offset into the array for the specific 9-element set you want. This is an optional parameter, defaulting to 0 if not given.
With the above matrix values in (for example) Array# 20, the sharpen convolution example might be:
MatrixConv(20,1,2)
...where the matrix is preloaded with the convolution values, the divisor is 1, and the intensity is 2. Note that, while the array handles assigned by ArtWonk's array management functions, AryInitNum and ArySaveNum, start at 100, you can use array handles 0-99 as "wild" arrays, outside of the array management system. This is useful for temporary, throw away arrays such as the parameter array used in this function.
Prototypes for Image Processing
InhibitPaint(bm=0) ~ Inhibit graphics display updates
AllowPaint(bm=0) ~ Allow graphics display updates (default)
ForcePaint(bm=0) ~ Force a graphics display update
AdjustHSL(H,S,L,bm=0) ~ HSL range -100 to 100
AdjustRGB(R,G,B,bm=0) ~ RGB range -255 to 255
AutoContrast(bm=0) ~ Automatically adjust contrast
Blend(pcnt,bm=0) ~ Blend each pixel with its neighboring pixels. Range: 0 to
100
Blur(bm=0) ~ Average each pixel with its neighboring pixels.
Brightness(pcnt,bm=0) ~ Brightens the image. Range: -100 to 100
Contrast(pcnt,bm=0) ~ Adjust contrast. Range: -100 to 100
Diffuse(bm=0) ~ Replaces each pixel with a randomly selected neighboring pixel.
Dilate(bm=0) ~ Dilates image using a 3x3 maximum filter
Emboss(bm=0) ~ Gives the image a raised metallic-like look
Equalize(bm=0) ~ Performs contrast equalization on the image
Erode(bm=0) ~ Erodes the image using a 3x3 minimum filter.
Flip(bm=0) ~ Flip image up/down
Gamma(amt,bm=0) ~ Gamma correct. Range: .01 to 10; 1=no correction.
MatrixConv(vAry,div,ints,ofst=0,bm=0) ~ vAry: (0-8) -32767 to 32767; div: -999
to 999; ints: 0 to 255
Median(bm=0) ~ Noise filters image using a 3x3 median filter
Mirror(bm=0) ~ Flip image left/right
MoBlur(ints,blurX,blurY,bm=0) ~ Ints: 1 to 25; blurX: -10 to 10; blurY: -10
to 10
Mosaic(amt,bm=0) ~ Pixelate image by amt block size. Range: 0 to 63
Negate(bm=0) ~ Creates a color negative of the image
Noise(freq,ints,bm=0) ~ Add noise. Freq: 1 to 20; ints: 1 to 128
Outline(bm=0) ~ Enhances edges
Parabolic(type,bm=0) ~ Brightness transform. Type: 0=convex; 1=concave
Perspective(type,pcnt,bm=0) ~ Type: 1=u/d; 2=d/u; 3=l/r; 4=r/l; pct: 0 to 100
Pinch(amt,bm=0) ~ Image looks pinched in the center. Amt: -100 to 100
Posterize(amt,bm=0) ~ Reduces the number of colors. Amt: 2 to 8
PolyWarp(x1,y1, x2,y2, x3, y3, x4,y4, bm=0) ~ polynomial warp based on points
within image
ReplaceColors(from,to,col,bm=0) ~ Replaces a range of colors. Params are color
values.
Ripple(freq,ints,dir,bm=0) ~ Freq: 1 to 100; ints: 1 to 100; dir: 0=horz, 1=vert
Rotate(angle,bm=0) ~ Rotate image. Angle: -360.00 to 360.00
Sharpen(amt,bm=0) ~ High pass convolution filter. Amt: 1 to 10
Soften(amt,bm=0) ~ Low pass convolution filter. Amt: 1 to 10
Solarize(threshold,bm=0) ~ Negates colors beyond the threshold value: 0 to 255
Swirl(angle,bm=0) ~ Swirl image from center. Angle: -360.00 to 360.00
Twist(size,rot,bm=0) ~ Size: 1 to 63; rot: 1=90; 2=180; 3=270; 4=random
Thes functions are similar to the Graphics modules draw functions, and they likewise operate on the Picture, not the Bitmap.
Prototypes for Graphics Drawing
DrawFillStyle(fillcolr, style=1, bm=0) ~ Fillstyle: 0 to 7; 0=Solid , 1=Transp,
etc.
DrawMode(mode=13, style=1,bm=0) ~ Mode: 1 to 16: 6=Invert, 7=Xor, 13=Copy; Style:
0 to 5
DrawWidth(width,bm=0) ~ Set outer line width: 1 to 32,767
DrawArc(x1,y1, x2,y2, StartAngle, EndAngle, color, bm=0) ~ Start & End Angle:
0-360
DrawEllipse(x,y, radius, color, aspect=1.0, bm=0) ~ Aspect of 1.0 gives circle
DrawBezier(x1,y1, x2,y2, x3, y3, x4,y4, color, bm=0) ~ x2,y2 & x3,y3 are
stretch points
DrawLine(x1,y1, x2,y2, color, box=0, fill=0, bm=0) ~ Box: 1=make box; fill:
1=solid fill
DrawPolyLine(N,Ax,Ay, color, last, Ox=0,Oy=0, bm=0) ~ N points from arrays Ax,
Ay; offset Ox,Oy
DrawWedge(x1,y1, x2,y2, StartAngle, EndAngle, color, bm=0) ~ Start & End
Angle: 0-360
DrawPolygon(sides, color, bm=0, x1,y1, x2,y2, [x3,y3 - x6,y6]) ~ Sides: 2-6
DrawRoundRect(x1,y1, x2,y2, rw, rh, color, bm=0) ~ rw, rh: width, height of
round corner
DrawText(x,y,"text", color, bm=0) ~ x,y = upper left corner of text
string
SetDrawFont(size=12, "font"="Tahoma", bold=0, italic=0,
uline=0, strike=0, bm=0)
The idea of turtle graphics is there is a turtle with a pen attached to its tail. You can tell it to move some number of steps (pixels); you can tell it to turn by an angle from 0 to 360 degrees, with 0 as north; and you can tell it to put its tail (pen) up to just move, or down to move and draw.
Prototypes for Turtle Graphics
TGHome(bm=0) ~ Put turtle in center of screen and pointing north
TGPlace(x, y, bm=0) ~ Place pen at x,y but don't move
TGNorth(bm=0) ~ point north
TGColor(color, bm=0) ~ set turtle pen color
TGTurn(degrees, bm=0) ~ set direction (0-360 for next movement)
TGMove(Pixels, Pen=1, bm=0) ~ Pen=1 draws, Pen=0 just moves
GetTGX(bm=0) ~ return current x
GetTGY(bm=0) ~ return currenty y
GetTGAngle(bm=0) ~ return current angle
GetAngleFromLine(x1,y1,x2,y2) ~ return angle from line endpoints
ArtWonk is Copyright © 2003-2007 by John Dunn and Algorithmic Arts. All Rights Reserved.