Cragmyre's Overlay Object

Index

Disclaimer

The author of this extension makes no claims concerning the fitness of this extension for any purpose whatsoever, and makes no gurantees, written or implied, of its level of security and safety to authors or to end users in any respect. You agree to use this extension at your own risk and to hold the author harmless in any event.

The Basics

The Overlay Object really has a two-fold purpose. Originally, it was designed to be an invisible "overlay" of your frame. The colors in object could be used to indicate particualr zones in your level. You could make certain things happen when objects were in those zones (over those colors). The second purpose, which was never the intent of the object when Cragmyre originally made it, is to be a graphical object. By turning visibility on, the Overlay becomes visible as a background object. Because it is a background object, any drawing to the screen or moving of its position forces the whole screen to be redrawn, which can be slow, so try to use the graphical features of this object efficiently.

Just a note about RGB values. If you enter values out of range (0-255), they will be rounded to either 0 or 255.

Conditions

Match Color
This condition retrieves the color at the specified point and compares it to the chosen color. Before comparing, the object rounds each color to one of the following: red, blue, green, yellow, magenta, cyan, black, or white. (This rounding is done by breaking both colors into RGB values and then rounding each value to either 0 or 255. Any value less than 128 is rounded to 0, and the rest are rounded to 255.) After the colors are rounded, the condition compares them and returns true if the two colors are the same.

Match Color using RGB
This condition retrieves the color at the specified point and compares it to the specified color. Before comparing, the object rounds each color to one of the following: red, blue, green, yellow, magenta, cyan, black, or white. (This rounding is done by breaking both colors into RGB values and then rounding each value to either 0 or 255. Any value less than 128 is rounded to 0, and the rest are rounded to 255.) After the colors are rounded, the condition compares them and returns true if the two colors are the same.

Compare Color to RGB Value
This condition retrieves the color at the specified point and compares it to the specified color or color range. You can specify a range of colors by using the "Make Range Value" expression on the appropriate RGB values. This condition returns true if the retrieved color is equal to the specified color or in the specified range.

Is X,Y outside Overlay?
This condition returns true if the given point is outside the bounds of the Overlay. It treats the point as an absolute position in the frame independent of the "Use Absolute Posistions" option.

Is Overlay Visible?
This condition returns true if the Overlay is visible.

Is Overlay Auto-Inking?
This condition returns true if the Overlay is currently auto-inking.

Has Overlay Finished Auto-Inking?
Events with this condition are executed as soon as auto-inking has finished (when the ink effect value has reached 0 or 128). You can use this condition in conjunction with the "Reverse Auto-Inking" action to create a ping-pong type of fade effect.

Actions

Update Display
This action forces MMF to immediately update the screen, showing any changes made to the Overlay since the last screen update.

Paste Object into Overlay
This action pastes the specified object into the Overlay.

Paste Overlay into Overlay
This action pastes the specified region of the specified Overlay into the specified region of the Overlay. If the destination width or height are 0, the value is adjusted to the width or height of the source. The source Overlay is specified by fixed value. Do not use values that are not retrieved from the "Get Fixed Value" expression. The source and destination Overlays may be the same.

Show/Hide Overlay
These actions toggle the visibility of the Overlay.

Turn Stretching On/Off
This action toggles Stretching. If Stretching is enabled, the Overlay is resized and repositioned to cover the entire frame. While enabled, change of position actions have no immediate effect. Those changes are stored, however, and are applied when Streching is disabled. When Stretching is disabled, the Overlay returns to its original size and position (unless the position was changed while Stretching was enabled, in which case it returns to the changed position).

Turn Automatic Display Update On/Off
This action toggles the automatic display updates. If this is enabled, at the end of every program loop, Overlay checks to see if it has been visibly changed (in other words, if it needs to update the display). If it has been changed, Overlay automatically redraws the frame. If this option is disabled, Overlay will not update the display at the end of program loops.

Turn Immediate Display Update On/Off
This action toggles immediate display updates. If this is enabled, Overlay will immediately force MMF to update the screen whenever the Overlay has been visibly modified. This method is very inefficient. It's use to not recommended. If it is disabled, the screen will not be immediately updated, which is the best way to go.

Set Functions to Use Absoulte Positions
This action sets the Overlay's functions to use absolute positions. This means that when this is enabed, coordinates passed to functions are relative to the top-left corner of the frame.

Set Functions to Use Relative Positions
This action sets the Overlay's functions to use relative positions. This means that when this is enabed, coordinates passed to functions are relative to the top-left corner of the Overlay object. (Note: Some conditions and actions are exempt from this setting.)

Keep Points After Plotting Polygon
This action sets the "Plot Polygon" function such that it does not erase the points of the polygon after plotting it.

Remove Points After Plotting Polygon
This action sets the "Plot Polygon" function such that it erases the points of the polygon after plotting it. The function will still reserve the memory for however many points were used.

Draw in Opaque Mode
This action sets Overlay to Opaque Mode. When this is enabled, RGB(0,0,0) is black.

Draw in Transparent Mode
This action sets Overlay to Transparent Mode. When this is enabled, RGB(0,0,0) is transparent. If you need black, use RGE(1,0,0) or something like that.

Set Ink Effect to None
This action sets the ink effect to None. If there is no ink effect, the Overlay is drawn normally.

Set Ink Effect to Semi-transparency
This action sets the ink effect to Semi-transparency. This will cause the Overlay to become translucent, enabling background objects behind the Overlay to become partially visible. The ink effect value determines to what degree the Overlay will be translucent.

Set Ink Effect to Invert
This action sets the ink effect to Invert. This will cause the Overlay's colors to become inverted when drawn on the screen. This does not affect the internal color make-up of the object.

Set Ink Effect to Xor
This action sets the ink effect to Xor. When the Overlay is being drawn, instead of each color overwriting the current background color, the colors are Xored, creating a new color.

Set Ink Effect to And
This action sets the ink effect to And. When the Overlay is being drawn, instead of each color overwriting the current background color, the colors are Anded, creating a new color.

Set Ink Effect to Or
This action sets the ink effect to Or. When the Overlay is being drawn, instead of each color overwriting the current background color, the colors are Ored, creating a new color.

Set Ink Effect to And Not
This action sets the ink effect to And Not. When the Overlay is being drawn, instead of each color overwriting the current background color, the Overlay color is Anded with the inverse of the background color, creating a new color.

Set Ink Effect by Number
This action sets the ink effect to the effect related to the specified number:
0: None
1: Semi-transparency
2: Invert
3: Xor
4: And
5: Or
6: And Not

Set Ink Effect Value
This action sets the ink effect value to the specified value. If the number is outside the range of 0-128, it is rounded. This value may or may not be used by the current ink effect.

Enable Anti-Aliasing
This action enables anti-aliasing of the Overlay. It is not a true anti-alias. The contours of the Overlay are simply blurred.

Disable Anti-Aliasing
This action disables anti-aliasing of the Overlay.

Start Auto-Inking
This action begins auto-inking using the specified speed. Auto-inking adds the given speed, which may be neagtive and/or floating point, to the ink effect value every MMF program loop. You can use it to create fading effects. It will automatically stop when the ink effect value reaches 0 or 128.

Stop Auto-Inking
This action stops the auto-inking. It does not change the speed, which can be retrieved if you wish to resume the effect at the same speed.

Reverse Auto-Inking
This action reverses the direction of the auto-inking. If the auto-inking was stopped, this action resumes it.

Set Position in Frame
This action sets the Overlay's position in the frame. It treats the point as an absolute position in the frame independent of the "Use Absolute Posistions" option. If Stretching is enabled, the change of position will occur when that option is disabled.

Set X Position in Frame
This action sets the Overlay's X position in the frame. It treats the position as an absolute position in the frame independent of the "Use Absolute Posistions" option. If Stretching is enabled, the change of position will occur when that option is disabled.

Set Y Position in Frame
This action sets the Overlay's Y position in the frame. It treats the position as an absolute position in the frame independent of the "Use Absolute Posistions" option. If Stretching is enabled, the change of position will occur when that option is disabled.

Resize Overlay
This action resizes the Overlay to the specified width and height, stretching the current image to the new size.

Load Image
This action loads the specified Bitmap file. If Stretching is enabled, the image is stretched to fir the frame. Otherwise, the Overlay is resized to fit the image.

Save Image
This action saves the current image data to a Bitmap file.

Use Color Chooser
These actions allow you to specify the color to be used by choosing it from the color selector.

Use RGB
These actions allow you to specify the color to be used by giving RGB values.

Use GetRGB
These actions all you to specify the color using MMF's built-in GetRGB(R,G,B) function. Additionally, these actions allow some new features to the normal drawing actions.

Clear Overlay
This action fills the entire Overlay with the specified color.

Flood Fill
This action fills in the region containing the specified point with the specified color. A region consists of a blob of a single color.

Change Old Color to New Color
This actions replaces all occurences of one color with a new color.

Set Pixel
This action sets the pixel at the specified point to the specified color.

Draw Line
This action draws a line of a specified color between two points.
Use GetRGB: Additionally, you can specify the width of the line.

Draw Rectangle
This action draws a rectangle of the specified color.
Use GetRGB: Additionally, you can specify the color and width of the outline. You can also use the No Fill Color to draw just an outline.

Draw Ellipse
This action draws an ellipse of the specified color.
Use GetRGB: Additionally, you can specify the color and width of the outline. You can also use the No Fill Color to draw just an outline.

Draw Polygon
This action (which is only under Use GetRGB) allows you to draw any arbitrary polygon with a specified outline size and color. You can also use the No Fill Color to draw just an outline. You specify the polygon to be drawn by creating a string containing the points of the vertices of the polygon. The string is of the format "(x1,y1) (x2,y2) (x3,y3)"... For example, you can draw a square with side length 50 at the origin using "(0,0) (0,50) (50,50) (50,0)".

Draw Shape
This action (which is only under Use GetRGB) allows you to draw any arbitrary shape with a specified outline size and color. You can also use the No Fill Color to draw just an outline. You specify the shape to be drawn by creating a string containing the points of the vertices of the shape. The string is of the format "(x1,y1) (x2,y2) (x3,y3)"... For example, you can draw a square with side length 50 at the origin using "(0,0) (0,50) (50,50) (50,0)". These points are sorted such that no two drawn segments will intersect. The sorting algorithm is rather slow (about order nn+2), so it may seem like it freezes when using many points.

Add Point to Plot
This action adds the specified point to the current plot.

Plot Ploygon
This action plots the specified polygon with a specified outline size and color. You can also use the No Fill Color to draw just an outline. The polygon uses all of the points added using "Add Points to Polygon" since the last "Plot Polygon" (if set to remove the points after plotting) or "Clear Points" action.

Plot Shape
This action plots the specified shape with a specified outline size and color. You can also use the No Fill Color to draw just an outline. The shape uses all of the points added using "Add Points to Plot" since the last "Plot Polygon" or "Plot Shape" (if set to remove the points after plotting) or "Clear Points" action. The points are sorted such that no two drawn segments will intersect. The sorting algorithm is rather slow (about order nn+2), so it may seem like it freezes when using many points.

Clear Points
This action clears all points from the polygon and frees up the memory they used. You should only use this action if you create many points infrequently. For reference, 1000 points used in a single polygon will reserve about 10 KB of memory (which isn't that much).

Expressions

Get Red(x,y)
ovlGetRed("Overlay", X, Y)
This expression returns the red RGB value of the color at the specified point.

Get Green(x,y)
ovlGetGreen("Overlay", X, Y)
This expression returns the green RGB value of the color at the specified point.

Get Blue(x,y)
ovlGetBlue("Overlay", X, Y)
This expression returns the blue RGB value of the color at the specified point.

Get ColorIndex(x,y)
ovlGetColorIndex("Overlay", X, Y)
This expression returns the color index value of the color at the specified point.

Get No Fill Color
ovlNoFillColor("Overlay")
This expression retruns the color index of the No Fill Color. This index is simply -1.

Make Color Range Value
ovlColorRange("Overlay", First Color, Last Color)
This expression returns the color range value for the range beginning with First Color and ending with Last Color, inclusive.

Get Color$(x,y)
ovlGetColor$("Overlay", X, Y)
This expression returns a string containing the name of the color at the specified point: Transparent, Red, Blue, Green, Yellow, Magenta, Cyan, Black, or White. It returns "Not Found" if the point is out of bounds.

Get RGB$(x,y)
ovlGetRGB$("Overlay", X, Y)
This expression returns a string containing the RGB values ("RGB(R,G,B)") of the color at the specified point. It returns "Not Found" if the point is out of bounds.

Get Ink Effect
ovlGetInkEffect("Overlay")
This expression returns the current ink effect. See the "Set Ink Effect by Number" action for what the returned number means.

Get Ink Effect Value
ovlGetInkValue("Overlay")
This expression returns the current ink effect value.

Get Auto-Inking Speed
ovlGetInkSpeed("Overlay")
This expression returns the speed of the auto-inking.

Get X Position of Overlay
ovlGetXPosition("Overlay")
This expression returns the X position of the Overlay in the frame.

Get Y Position of Overlay
ovlGetYPosition("Overlay")
This expression returns the Y position of the Overlay in the frame.

Get Width of Overlay
ovlGetWidth("Overlay")
This expression returns the width of the Overlay.

Get Height of Overlay
ovlGetHeight("Overlay")
This expression returns the height of the Overlay.

Get Address of Overlay
ovlAddress("Overlay")
This expression returns the address of the Overlay. This value is used in selecting specific Overlays.