CustomImage
com.jsmacrosce.jsmacros.client.api.classes.CustomImage
An image a script can draw on and hand to the game as a texture.
Drawing calls change the in-memory image; call update() to upload those pixels to its game texture. Updates upload the whole image, so they can be batched after several drawing calls.
Images register under minecraft:jsmimage/<name>; getIdentifier() returns that identifier. Creating another image with the same name registers it under the same identifier.
A script gets one through createWidget(int, int, String) for a blank one or createWidget(String, String) for one loaded from a file, and the class is available through the ScriptClasses.CustomImage type namespace.
js
// Draw several changes before uploading the image once.
const img = ScriptClasses.CustomImage.createWidget(16, 16, "badge");
img.setGraphicsColor(Color.rgb(0xFF, 0x55, 0x55));
img.fillRect(0, 0, 16, 16);
img.setGraphicsColor(Color.rgb(0xFF, 0xFF, 0xFF));
img.drawString(2, 11, "hi");
img.update();
Chat.log(`${img.getIdentifier()} is ${img.getWidth()} by ${img.getHeight()}`);Available in scripts as ScriptClasses.CustomImage.
Constructors
new CustomImage
Makes an image from an existing one, using the next automatically assigned numeric name. The counter is shared by all instances.
Parameters:
image: the image to draw on and to hand to the game
Makes an image from an existing one under the given name. The name is appended to
jsmimage/ and parsed as a resource identifier, with the default minecraft namespace. Invalid identifier paths are rejected. The constructor registers and uploads the image before returning; an existing identifier is reused.Parameters:
image: the image to draw on and to hand to the gamename: the identifier-path name to register it under, without thejsmimage/prefix
Fields
IMAGES
Images created by this class, keyed by their full resource identifier (the value returned by getIdentifier()). A missing key returns
null; creating an image with an existing identifier replaces that map entry. // Look up an image by its full identifier.
const made = ScriptClasses.CustomImage.createWidget(16, 16, "overlay");
const found = ScriptClasses.CustomImage.IMAGES.get(`minecraft:jsmimage/${made.getName()}`);
if (found !== null) {
Chat.log(`found the overlay at ${found.getWidth()} by ${found.getHeight()}`);
}Methods
clearRect
Clears the rectangle using the graphics background color, which is separate from the drawing color. Use the overload with a
color argument to choose the background color for this operation.Parameters:
x: the x position of the rectangley: the y position of the rectanglewidth: the width of the rectangleheight: the height of the rectangle
Returns: self for chaining.
Clears the rectangle using
color, then restores the previous graphics background.Parameters:
x: the x position of the rectangley: the y position of the rectanglewidth: the width of the rectangleheight: the height of the rectanglecolor: the rgb color to fill the rectangle with
Returns: self for chaining.
clipRect
clipRect(int x, int y, int width, int height): CustomImage#Intersects the current clip with the specified rectangle, restricting subsequent drawing to the intersection. The clip follows the graphics transform, including translations.
Parameters:
x: the x coordinate of the rectangle to intersect the clip withy: the y coordinate of the rectangle to intersect the clip withwidth: the width of the rectangle to intersect the clip withheight: the height of the rectangle to intersect the clip with
Returns: self for chaining.
copyArea
Copies a region of this image to another location in the same image.
dx and dy are offsets from the source region's origin; overlapping source and destination regions are supported.Parameters:
x: the x position to copy fromy: the y position to copy fromwidth: the width of the area to copyheight: the height of the area to copydx: the offset to the x position to copy tody: the offset to the y position to copy to
Returns: self for chaining.
createWidget
Creates a transparent image with the specified dimensions. Its name is used for game registration, and this API does not resize it.
Parameters:
width: the width of the image in pixelsheight: the height of the image in pixelsname: the name to register it under, without thejsmimage/prefix
Returns: a new blank image
Loads an image from a path relative to the JsMacros config folder. The loaded dimensions come from the file;
name is its game registration name, not the file name. Logs an error and returns null if reading fails or no image reader recognizes the file.Parameters:
path: the path to the image, relative to the jsMacros config foldername: the name to register it under, without thejsmimage/prefix
Returns: a new image, or
null if the file is unreadable or has an unsupported formatdraw3DRect
Draws a 3D-effect rectangle outline. The drawing color supplies the line and the graphics background supplies the shading;
raised selects raised or etched shading.Parameters:
x: the x position to draw the 3D rectangle aty: the y position to draw the 3D rectangle atwidth: the width of the 3D rectangleheight: the height of the 3D rectangleraised: whether the rectangle should be raised above the surface or etched into the surface
Returns: self for chaining.
drawArc
Draws an unfilled arc of the oval bounded by the specified rectangle. Angles are in degrees;
0 is at three o'clock and positive angles proceed anticlockwise.Parameters:
x: the x position to draw the arc aty: the y position to draw the arc atwidth: the width of the archeight: the height of the arcstartAngle: the beginning anglearcAngle: the angular extent of the arc, relative to the start angle
Returns: self for chaining.
drawImage
Draws the entire source image into this image at the specified destination size, scaling it as needed. Changes remain in memory until update() uploads them.
Parameters:
img: the image to draw onto this imagex: the x position to draw the image aty: the y position to draw the image atwidth: the width of the image to drawheight: the height of the image to draw
Returns: self for chaining.
drawImage(Image img, int x, int y, int width, int height, int sourceX, int sourceY, int sourceWidth, int sourceHeight): CustomImageSince1.8.4#Draws the source rectangle
(sourceX, sourceY, sourceWidth, sourceHeight) into the destination rectangle (x, y, width, height) on this image. The destination is scaled as needed; changes remain in memory until update() uploads them.Parameters:
img: the image to draw onto this imagex: the x position to draw the image aty: the y position to draw the image atwidth: the width of the image to drawheight: the height of the image to drawsourceX: the x position of the subimage to drawsourceY: the y position of the subimage to drawsourceWidth: the width of the subimage to drawsourceHeight: the height of the subimage to draw
Returns: self for chaining.
drawLine
Draws a one-pixel line in the current graphics color.
Parameters:
x1: the first x position of the liney1: the first y position of the linex2: the second x position of the liney2: the second y position of the line
Returns: self for chaining.
drawOval
Draws the outline of an oval bounded by the specified rectangle, using the drawing color.
Parameters:
x: the x position to draw the oval aty: the y position to draw the oval atwidth: the width of the ovalheight: the height of the oval
Returns: self for chaining.
drawPolygon
Draws a closed polygon outline through corresponding entries of the coordinate arrays. If their lengths differ, entries beyond the shorter array are ignored.
Parameters:
pointsX: an array of all x positions of the points in the polygonpointsY: an array of all y positions of the points in the polygon
Returns: self for chaining.
drawPolygonLine
Draws an open polyline through corresponding entries of the coordinate arrays. If their lengths differ, entries beyond the shorter array are ignored; the last point is not joined to the first unless the supplied points do so.
Parameters:
pointsX: an array of all x positions of the points in the polygonpointsY: an array of all y positions of the points in the polygon
Returns: self for chaining.
drawRect
Draws a rectangle outline in the current graphics color.
Parameters:
x: the x position of the rectangley: the y position of the rectanglewidth: the width of the rectangleheight: the height of the rectangle
Returns: self for chaining.
drawRoundRect
drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight): CustomImageSince1.8.4#Draws a rounded-rectangle outline;
arcWidth and arcHeight specify the corner arc diameters.Parameters:
x: the x position to draw the rectangle aty: the y position to draw the rectangle atwidth: the width of the rectangleheight: the height of the rectanglearcWidth: the horizontal diameter of the arc at the four cornersarcHeight: the vertical diameter of the arc at the four corners
Returns: self for chaining.
drawString
Draws text in the image graphics' current font and drawing color. The y coordinate is the text baseline, not its top.
Parameters:
x: the x position to draw the string aty: the y position to draw the string attext: the text to draw
Returns: self for chaining.
fill3DRect
Fills a 3D-effect rectangle using the drawing color; the graphics background supplies the shading, and
raised selects raised or etched shading.Parameters:
x: the x position to draw the 3D rectangle aty: the y position to draw the 3D rectangle atwidth: the width of the 3D rectangleheight: the height of the 3D rectangleraised: whether the rectangle should be raised above the surface or etched into the surface
Returns: self for chaining.
fillArc
Fills the arc segment of the bounded oval using the drawing color. Angles follow drawArc(int, int, int, int, int, int):
0 is at three o'clock and positive angles proceed anticlockwise.Parameters:
x: the x position to draw the arc aty: the y position to draw the arc atwidth: the width of the archeight: the height of the arcstartAngle: the beginning anglearcAngle: the angular extent of the arc, relative to the start angle
Returns: self for chaining.
fillOval
Fills an oval bounded by the specified rectangle using the drawing color.
Parameters:
x: the x position to draw the oval aty: the y position to draw the oval atwidth: the width of the ovalheight: the height of the oval
Returns: self for chaining.
fillPolygon
Fills the polygon defined by corresponding entries of the coordinate arrays. If their lengths differ, entries beyond the shorter array are ignored.
Parameters:
pointsX: an array of all x positions of the points in the polygonpointsY: an array of all y positions of the points in the polygon
Returns: self for chaining.
fillRect
Fills a rectangle in the current graphics color.
Parameters:
x: the x position of the rectangley: the y position of the rectanglewidth: the width of the rectangleheight: the height of the rectangle
Returns: self for chaining.
fillRoundRect
fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight): CustomImageSince1.8.4#Fills a rounded rectangle using the drawing color;
arcWidth and arcHeight specify the corner arc diameters.Parameters:
x: the x position to draw the rectangle aty: the y position to draw the rectangle atwidth: the width of the rectangleheight: the height of the rectanglearcWidth: the horizontal diameter of the arc at the four cornersarcHeight: the vertical diameter of the arc at the four corners
Returns: self for chaining.
getClipBounds
getGraphicsColor
Returns the current graphics drawing color as an ARGB integer. The color is opaque and is separate from pixel values.
Returns: the graphics current rgb color.
getHeight
Returns the image height in pixels. It is fixed when the image is created.
Returns: the height of this image.
getIdentifier
getImage
Returns the mutable internal image, not a copy. Changes made through it affect the pixels used by this CustomImage and are included by the next update().
Returns: the internal BufferedImage of this image, which all updates are made to.
getName
getPixel
Returns the pixel at
(x, y) as an ARGB integer. Coordinates outside the image are rejected by the underlying image implementation.Parameters:
x: the x position to get the color fromy: the y position to get the color from
Returns: the color at the given position.
getStringWidth
getWidth
Returns the image width in pixels. It is fixed when the image is created.
Returns: the width of this image.
loadImage
Loads an image from a path relative to the JsMacros config folder. Returns
null if reading fails or no image reader recognizes the file; I/O exceptions are logged. The result is an ordinary BufferedImage, not a registered game texture. // Load an image file and draw it when recognized.
const img = ScriptClasses.CustomImage.createWidget(32, 32, "canvas");
const source = img.loadImage("images/logo.png");
if (source !== null) {
img.drawImage(source, 0, 0, 32, 32);
img.update();
}Parameters:
path: the path to the image, relative to the jsMacros config folder
Returns: an image from the given path, or
null if the file could not be read or is not an imageLoads a file relative to the JsMacros config folder and returns the requested crop as a BufferedImage. A file that cannot be read or is not an image returns
null, as in loadImage(String). Coordinates are measured from the image's top-left; an invalid crop, including one outside the image, throws RasterFormatException. The returned subimage shares pixel data with the loaded image.Parameters:
path: the path to the image, relative to the jsMacros config folderx: the x position to get the subimage fromy: the y position to get the subimage fromwidth: the width of the subimageheight: the height of the subimage
Returns: the cropped image from the given path, or
null if the file could not be read or is not an imagenativeARGBFlip
Returns
argb with its red and blue bytes exchanged; the alpha and green bytes are unchanged. This arithmetic helper does not modify an image.Parameters:
argb: the ARGB value to transform
Returns: the value with its red and blue bytes exchanged
saveImage
Saves the current pixels as a PNG under the JsMacros config folder. The path is relative to that folder,
.png is appended to fileName, and an existing file is overwritten. I/O failures are logged rather than thrown; the returned value does not indicate whether writing succeeded. This saves the in-memory image, whether or not update() has uploaded recent changes.Parameters:
path: the path to the image, relative to the jsMacros config folderfileName: the file name of the image, without the extension
Returns: self for chaining.
setClip
Replaces the current clip with the specified rectangle, rather than intersecting it with the current clip as clipRect(int, int, int, int) does.
Parameters:
x: the x coordinate of the new clip rectangley: the y coordinate of the new clip rectanglewidth: the width of the new clip rectangleheight: the height of the new clip rectangle
Returns: self for chaining.
setGraphicsColor
Sets the opaque graphics drawing color used by drawing operations. The alpha bits of
color are ignored; this does not set the background used by clearRect(int, int, int, int).Parameters:
color: the rgb color to use for graphics operations
Returns: self for chaining.
setPaintMode
Restores ordinary paint mode after setXorMode(int).
Returns: self for chaining.
setPixel
Sets one pixel in the in-memory image from an ARGB integer; call update() to upload the change to its texture. This does not change the graphics drawing color. Coordinates outside the image are rejected by the underlying image implementation.
Parameters:
x: the x position to set the color aty: the y position to set the color atargb: the ARGB value to set the pixel to
Returns: self for chaining.
setXorMode
Sets XOR paint mode with
color as the XOR color. The mode remains active until setPaintMode() is called.Parameters:
color: the color to use for the xor operation
Returns: self for chaining.
translate
Translates the graphics origin for subsequent drawing operations. The translation is cumulative; it does not move existing pixels.
Parameters:
x: the x position of the origin pointy: the y position of the origin point
Returns: self for chaining.
update
Uploads this image's pixels to its texture so changes become visible. The full image is copied and uploaded; batch drawing changes and call this once afterward. The upload is scheduled on the client thread and this method waits for it unless the waiting thread is interrupted. A new image is uploaded during construction.
Returns: self for chaining.