Package dev.cerus.maps.api.graphics

Class MapGraphics<C,P>

java.lang.Object

dev.cerus.maps.api.graphics.MapGraphics<C,P>

Type Parameters:

C - The render target (e.g. ClientsideMap)

P - The render params

Direct Known Subclasses:

ClientsideMapGraphics, FastMapScreenGraphics, MapScreenGraphics, StandaloneMapGraphics

public abstract class MapGraphics<C,P>
extends Object

The 2D rendering engine for maps. Implementations only need to take care of pixel setting and retrieving.

This class is huge and should maybe be split into multiple classes, but I haven't found an elegant solution yet.

Constructor Summary

Constructors

Constructor	Description
MapGraphics()

Method Summary

Modifier and Type	Method	Description
void	applyFilterToArea(Filter filter, int x, int y, int width, int height)	Apply a filter to a rectangular area
void	boxBlur(int x, int y, int width, int height)	Perform box blur on a rectangular area
void	boxBlur(int passes, int x, int y, int width, int height)	Perform box blur on a rectangular area
void	boxBlur(int passes, BoxBlurFilter.TransparencyHandling transparencyHandling, int x, int y, int width, int height)	Perform box blur on a rectangular area
void	boxBlur(BoxBlurFilter.TransparencyHandling transparencyHandling, int x, int y, int width, int height)	Perform box blur on a rectangular area
protected byte	calculateComposite(byte source, byte dest, float alpha)	Composite two colors together
protected int	composite(int comp1, int comp2, float a)	Calculate the new component value for two color components with a specific alpha value.
void	compositeAtop(MapGraphics<?,?> graphics, int atX, int atY)	Perform an 'atop' alpha composition.
void	compositeIn(MapGraphics<?,?> graphics, int atX, int atY)	Perform an 'in' alpha composition.
void	compositeOut(MapGraphics<?,?> graphics, int atX, int atY)	Perform an 'out' alpha composition.
void	compositeOver(MapGraphics<?,?> graphics, int atX, int atY)	Perform an 'over' alpha composition.
void	compositeXor(MapGraphics<?,?> graphics, int atX, int atY)	Perform an 'xor' alpha composition.
abstract MapGraphics<C,P>	copy()	Make a copy of this buffer
void	drawEllipse(int atX, int atY, int widthRad, int heightRad, byte color)
void	drawEllipse(int atX, int atY, int widthRad, int heightRad, byte color, float alpha)	Outlines an ellipse using the midpoint ellipse algorithm
void	drawImage(BufferedImage img, int x, int y)	Draws an image onto the graphics buffer
void	drawLine(int x1, int y1, int x2, int y2, byte color, float alpha)	Draws a line
void	drawLine(Vec2 v1, Vec2 v2, byte color, float alpha)	Draws a line
protected void	drawLineX(int x1, int x2, int y, byte color, float alpha)
protected void	drawLineY(int y1, int y2, int x, byte color, float alpha)
void	drawRect(int x, int y, int w, int h, byte color, float alpha)	Outlines a rectangle
void	drawText(int x, int y, String text, byte color, int size)	Draws text
void	drawText(int x, int y, String text, MapFont font, byte color, int size)	Draws text
void	fill(int x, int y, byte color, float alpha)	Perform a flood fill operation at a specific coordinate
void	fillComplete(byte color)	Fills the whole buffer with a specific color
void	fillRect(int x, int y, int w, int h, byte color, float alpha)	Draws and fills a rectangle
void	fillWithBuffer(MapGraphics<?,?> graphics, float alpha, boolean ignoreTransparent)
byte[]	getDirectAccessData()
abstract int	getHeight()	Get the height in pixels of this buffer
abstract byte	getPixel(int x, int y)	Get a pixel
abstract int	getWidth()	Get the width in pixels of this buffer
void	grayscale(int x, int y, int width, int height)	Grayscale a rectangular area
boolean	hasDirectAccessCapabilities()
int	index(int x, int y)
int	index(int x, int y, int w, int h)
boolean	isTransparent(byte color)	Returns true when the specified color is transparent.
static MapGraphics<MapGraphics<?,?>,?>	newGraphicsObject(int width, int height)	Creates a new standalone graphics instance
protected float	normalizeAlpha(float a)
void	place(MapGraphics<?,?> graphics, int x, int y)	Copy the contents of the specified graphics instance onto the buffer of this graphics instance at the specified position
void	place(MapGraphics<?,?> graphics, int x, int y, float alpha)	Copy the contents of the specified graphics instance onto the buffer of this graphics instance at the specified position
void	place(MapGraphics<?,?> graphics, int x, int y, float alpha, boolean ignoreTransparent)	Copy the contents of the specified graphics instance onto the buffer of this graphics instance at the specified position
void	renderOnto(C renderTarget)	Basically copies this buffer onto the buffer of the specified render target
abstract void	renderOnto(C renderTarget, P params)	Basically copies this buffer onto the buffer of the specified render target
void	replace(byte colorToReplace, byte color)	Replace a color with another color across the whole buffer
byte	setPixel(int x, int y, byte color)	Set a pixel
abstract byte	setPixel(int x, int y, float alpha, byte color)	Set a pixel
static MapGraphics<MapGraphics<?,?>,?>	standalone(int width, int height)	Creates a new standalone graphics instance

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MapGraphics

public MapGraphics()

Method Details

standalone

public static MapGraphics<MapGraphics<?,?>,?> standalone(int width,
 int height)

Creates a new standalone graphics instance

Parameters:

width - Width of the graphics

height - Height of the graphics

Returns:

New standalone graphics

newGraphicsObject

public static MapGraphics<MapGraphics<?,?>,?> newGraphicsObject(int width,
 int height)

Creates a new standalone graphics instance

Parameters:

width - Width of the graphics

height - Height of the graphics

Returns:

New standalone graphics

compositeOver

public void compositeOver(MapGraphics<?,?> graphics,
 int atX,
 int atY)

Perform an 'over' alpha composition. See https://cerus.dev/img/maps_alpha_composition.png

 # = Non transparent pixel with color from this instance
 % = Non transparent pixel with color from the other instance

                *  *
            * %%%%%%%% *
          * %% OTHER %%% *
          * %%%%%%%%%%%% *
     +----------+ %%%% *
     | # THIS # |  *
     | ######## |
     +----------+
 

Parameters:

graphics - The graphics instance to composite

atX - The x coordinate where the composition should start

atY - The y coordinate where the composition should start

compositeIn

public void compositeIn(MapGraphics<?,?> graphics,
 int atX,
 int atY)

Perform an 'in' alpha composition. See https://cerus.dev/img/maps_alpha_composition.png

 # = Non transparent pixel with color from this instance
 % = Non transparent pixel with color from the other instance

                *  *
            *          *
          *    OTHER     *
          *              *
     +-------####      *
     |   THIS  ##  *
     |          |
     +----------+
 

Parameters:

graphics - The graphics instance to composite

atX - The x coordinate where the composition should start

atY - The y coordinate where the composition should start

compositeOut

public void compositeOut(MapGraphics<?,?> graphics,
 int atX,
 int atY)

Perform an 'out' alpha composition. See https://cerus.dev/img/maps_alpha_composition.png

 # = Non transparent pixel with color from this instance
 % = Non transparent pixel with color from the other instance

                *  *
            *          *
          *    OTHER     *
          *              *
     +------*          *
     | # THIS # *  *
     | ######## |
     +----------+
 

Parameters:

graphics - The graphics instance to composite

atX - The x coordinate where the composition should start

atY - The y coordinate where the composition should start

compositeAtop

public void compositeAtop(MapGraphics<?,?> graphics,
 int atX,
 int atY)

Perform an 'atop' alpha composition. See https://cerus.dev/img/maps_alpha_composition.png

 # = Non transparent pixel with color from this instance
 % = Non transparent pixel with color from the other instance

                *  *
            * %%%%%%%% *
          * %% OTHER %%% *
          * %%%%%%%%%%%% *
     +-------####%%%%% *
     |   THIS  ##% *
     |          |
     +----------+
 

Parameters:

graphics - The graphics instance to composite

atX - The x coordinate where the composition should start

atY - The y coordinate where the composition should start

compositeXor

public void compositeXor(MapGraphics<?,?> graphics,
 int atX,
 int atY)

Perform an 'xor' alpha composition. See https://cerus.dev/img/maps_alpha_composition.png

 # = Non transparent pixel with color from this instance
 % = Non transparent pixel with color from the other instance

                *  *
            * %%%%%%%% *
          * %% OTHER %%% *
          * %%%%%%%%%%%% *
     +----------+ %%%% *
     | # THIS   |  *
     | ######## |
     +----------+
 

Parameters:

graphics - The graphics instance to composite

atX - The x coordinate where the composition should start

atY - The y coordinate where the composition should start

fillWithBuffer

public void fillWithBuffer(MapGraphics<?,?> graphics,
 float alpha,
 boolean ignoreTransparent)

place

public void place(MapGraphics<?,?> graphics,
 int x,
 int y)

Copy the contents of the specified graphics instance onto the buffer of this graphics instance at the specified position

Parameters:

graphics - The graphics instance to copy from

x - X coordinate

y - Y coordinate

place

public void place(MapGraphics<?,?> graphics,
 int x,
 int y,
 float alpha)

Copy the contents of the specified graphics instance onto the buffer of this graphics instance at the specified position

Parameters:

graphics - The graphics instance to copy from

x - X coordinate

y - Y coordinate

alpha - The alpha value of the contents

place

public void place(MapGraphics<?,?> graphics,
 int x,
 int y,
 float alpha,
 boolean ignoreTransparent)

Copy the contents of the specified graphics instance onto the buffer of this graphics instance at the specified position

Parameters:

graphics - The graphics instance to copy from

x - X coordinate

y - Y coordinate

alpha - The alpha value of the contents

ignoreTransparent - Should transparent pixels not be copied?

grayscale

public void grayscale(int x,
 int y,
 int width,
 int height)

Grayscale a rectangular area

Parameters:

x - X coordinate

y - Y coordinate

width - Area width

height - Area height

boxBlur

public void boxBlur(int x,
 int y,
 int width,
 int height)

Perform box blur on a rectangular area

Parameters:

x - X coordinate

y - Y coordinate

width - Area width

height - Area height

boxBlur

public void boxBlur(BoxBlurFilter.TransparencyHandling transparencyHandling,
 int x,
 int y,
 int width,
 int height)

Perform box blur on a rectangular area

Parameters:

transparencyHandling - How transparent pixels should be handled

x - X coordinate

y - Y coordinate

width - Area width

height - Area height

boxBlur

public void boxBlur(int passes,
 int x,
 int y,
 int width,
 int height)

Perform box blur on a rectangular area

Parameters:

passes - The intensity of the blur (2-5 for best effect)

x - X coordinate

y - Y coordinate

width - Area width

height - Area height

boxBlur

public void boxBlur(int passes,
 BoxBlurFilter.TransparencyHandling transparencyHandling,
 int x,
 int y,
 int width,
 int height)

Perform box blur on a rectangular area

Parameters:

passes - The intensity of the blur (2-5 for best effect)

transparencyHandling - How transparent pixels should be handled

x - X coordinate

y - Y coordinate

width - Area width

height - Area height

applyFilterToArea

public void applyFilterToArea(Filter filter,
 int x,
 int y,
 int width,
 int height)

Apply a filter to a rectangular area

Parameters:

filter - The filter to apply

x - X coordinate

y - Y coordinate

width - Area width

height - Area height

fill

public void fill(int x,
 int y,
 byte color,
 float alpha)

Perform a flood fill operation at a specific coordinate

Will do nothing if the color at the starting coordinate is the same as the fill color.

Parameters:

x - The starting x coordinate

y - The starting y coordinate

color - The color to fill with

alpha - The alpha of the filling color

fillComplete

public void fillComplete(byte color)

Fills the whole buffer with a specific color

Parameters:

color - The color to fill the buffer with

fillRect

public void fillRect(int x,
 int y,
 int w,
 int h,
 byte color,
 float alpha)

Draws and fills a rectangle

Parameters:

x - The x coordinate

y - The y coordinate

w - The width

h - The height

color - The fill color

alpha - The alpha of the rectangle

drawRect

public void drawRect(int x,
 int y,
 int w,
 int h,
 byte color,
 float alpha)

Outlines a rectangle

Parameters:

x - The x coordinate

y - The y coordinate

w - The width

h - The height

color - The outline color

alpha - The alpha of the rectangle

drawLine

public void drawLine(int x1,
 int y1,
 int x2,
 int y2,
 byte color,
 float alpha)

Draws a line

Parameters:

x1 - The starting x coordinate

y1 - The starting y coordinate

x2 - The finishing x coordinate

y2 - The finishing y coordinate

color - The outline color

alpha - The alpha of the rectangle

drawLineX

protected void drawLineX(int x1,
 int x2,
 int y,
 byte color,
 float alpha)

drawLineY

protected void drawLineY(int y1,
 int y2,
 int x,
 byte color,
 float alpha)

drawLine

public void drawLine(Vec2 v1,
 Vec2 v2,
 byte color,
 float alpha)

Draws a line

Parameters:

v1 - The starting coordinate

v2 - The finishing coordinate

color - The outline color

alpha - The alpha of the rectangle

drawImage

public void drawImage(BufferedImage img,
 int x,
 int y)

Draws an image onto the graphics buffer

Parameters:

img - The image to draw

x - The x coordinate where the image should be drawn

y - The y coordinate where the image should be drawn

drawText

public void drawText(int x,
 int y,
 String text,
 byte color,
 int size)

Draws text

Parameters:

x - X coordinate

y - Y coordinate

text - The text

color - The color

size - The size multiplier (1 = normal)

drawText

public void drawText(int x,
 int y,
 String text,
 MapFont font,
 byte color,
 int size)

Draws text

This method was originally copied from Bukkit. It has been heavily modified since then to fit our needs.

Parameters:

x - X coordinate

y - Y coordinate

text - The text

font - The font

color - The color

size - The size multiplier (1 = normal)

drawEllipse

public void drawEllipse(int atX,
 int atY,
 int widthRad,
 int heightRad,
 byte color)

drawEllipse

public void drawEllipse(int atX,
 int atY,
 int widthRad,
 int heightRad,
 byte color,
 float alpha)

Outlines an ellipse using the midpoint ellipse algorithm

https://www.geeksforgeeks.org/midpoint-ellipse-drawing-algorithm/

Parameters:

atX - Center x of the ellipse

atY - Center y of the ellipse

widthRad - Horizontal radius

heightRad - Vertical radius

color - Color of the ellipse

alpha - Alpha of the ellipse

replace

public void replace(byte colorToReplace,
 byte color)

Replace a color with another color across the whole buffer

Parameters:

colorToReplace - The color to replace

color - The color to replace the other color with

setPixel

public byte setPixel(int x,
 int y,
 byte color)

Set a pixel

Parameters:

x - The x coordinate

y - The y coordinate

color - The pixel color

Returns:

The old pixel color. Might return the specified color if the method does not end up setting the pixel.

setPixel

public abstract byte setPixel(int x,
 int y,
 float alpha,
 byte color)

Set a pixel

Parameters:

x - The x coordinate

y - The y coordinate

alpha - The pixel alpha

color - The pixel color

Returns:

The old pixel color. Might return the specified color if the method does not end up setting the pixel.

getPixel

public abstract byte getPixel(int x,
 int y)

Get a pixel

Parameters:

x - The x coordinate

y - The y coordinate

Returns:

The pixels color

calculateComposite

protected byte calculateComposite(byte source,
 byte dest,
 float alpha)

Composite two colors together

See https://en.wikipedia.org/wiki/Alpha_compositing

Parameters:

source - The new color

dest - The old color (e.g. background)

alpha - The alpha

Returns:

The composited color

composite

protected int composite(int comp1,
 int comp2,
 float a)

Calculate the new component value for two color components with a specific alpha value. A color component is either red, green or blue.

Example:

     Color someColor = new Color(0, 0, 0);
     Color background = new Color(255, 255, 255);
     float alpha = 0.5f;
     Color newColor = new Color(
         composite(someColor.getRed(), background.getRed(), alpha),
         composite(someColor.getGreen(), background.getGreen(), alpha),
         composite(someColor.getBlue(), background.getBlue(), alpha)
     );
     // newColor ==> java.awt.Color[r=127,g=127,b=127]
 

Parameters:

comp1 - First component

comp2 - Second component

a - Alpha

Returns:

New component

isTransparent

public boolean isTransparent(byte color)

Returns true when the specified color is transparent.

Technically there are 4 transparent colors (0 - 3), but we only return true on 0. This is because we use 0 to mark the absence of a color. This allows us to use 1 - 3 as transparent colors in other processing methods (blending for example).

Implementations of this class are allowed to modify this to suit their needs, but that could affect the functionality of other default features.

Parameters:

color - The color to check

Returns:

True if transparent

normalizeAlpha

protected float normalizeAlpha(float a)

renderOnto

public void renderOnto(C renderTarget)

Basically copies this buffer onto the buffer of the specified render target

Parameters:

renderTarget - The render target

renderOnto

public abstract void renderOnto(C renderTarget,
 P params)

Basically copies this buffer onto the buffer of the specified render target

Parameters:

renderTarget - The render target

params - The render parameters

copy

public abstract MapGraphics<C,P> copy()

Make a copy of this buffer

Returns:

A copy of this buffer

getWidth

public abstract int getWidth()

Get the width in pixels of this buffer

Returns:

The width

getHeight

public abstract int getHeight()

Get the height in pixels of this buffer

Returns:

The height

hasDirectAccessCapabilities

public boolean hasDirectAccessCapabilities()

getDirectAccessData

public byte[] getDirectAccessData()

index

public int index(int x,
 int y)

index

public int index(int x,
 int y,
 int w,
 int h)