[ Prev | Index | Next ]
Japanese English

Sprite-Based Drawing

In addition to direct drawing, which we've covered so far, VCSSL also supports a method called sprite-based drawing. This section explains how sprite-based drawing works.

Sponsored Link


What Is Sprite-Based Drawing?

Sprite-based drawing is a software implementation of a feature that was originally implemented in hardware during the golden era of 2D graphics -- especially in games.

Conceptually, it's very similar to the use of animation cels in traditional animation production. Specifically, you register a set of individual "layers" called sprites in the renderer -- one for each shape or image you want to draw. Then, when it's time to render, the renderer composites those sprites together into a single image.

Sprite-based drawing is particularly effective for animation.

For example, imagine an animation scene where some elements move and others stay static. If you were using direct drawing, you'd need to clear the background and redraw everything -- backgrounds, characters, effects -- using draw functions for each frame.

With sprite-based drawing, you can register all the elements as sprites once at the beginning, and then simply update the position or appearance of only the ones that change. This can make your code simpler and more manageable.

Sprite-based drawing is also slightly faster than direct drawing in some cases. However, unless you're drawing tens or hundreds of thousands of sprites, the performance difference on a scripting platform like VCSSL is usually negligible. In practice, just choose whichever method keeps your code cleaner.

Basic Sprite Operations

Unlike direct drawing, sprites are designed to be manipulated dynamically at runtime -- moved, recolored, and more. So before diving into how to create each sprite type, let's go over the basic operations for using them.

Basic Sprite Operations

Unlike direct drawing, sprites are designed to be manipulated dynamically at runtime -- moved, recolored, and more. So before diving into how to create each sprite type, let's go over the basic operations for using them.

- Function Format -
int new`Sprite ( ` )

This function creates a new sprite and returns its unique identifier, known as the sprite ID.

Registering Sprites

Sprites won't appear on screen unless you register them with a renderer. To register a sprite, use the "mountSprite" function.

- Function Format -
void mountSprite ( int spriteID, int rendererID )

Arguments:

  • spriteID: The ID of the sprite to register.
  • rendererID: The ID of the renderer to register it with.

Rendering Sprites

Once all the sprites are registered with the renderer, you'll need to actually composite and render them into the graphics resource.

For this, use the "paintGraphics2D" function.

- Function Format -
void paintGraphics2D ( int rendererID )

Arguments:

  • rendererID: The ID of the renderer.

Note: The sprites will not be composited or displayed until this function is called.

Types of Sprites

VCSSL provides a variety of sprite types: for drawing shapes like lines and polygons, for rendering text, or for displaying images. This section explains how to create and use each type.

All of the functions below return the ID of the newly created sprite.

Point Sprite

To create a point sprite, use the "newPointSprite" function.

- Function Format -
int newPointSprite ( int x, int y, int radius )

Arguments:

  • x, y: The coordinates of the point.
  • radius: The radius of the point.

Line Sprite

To create a line sprite, use the "newLineSprite" function.

- Function Fromat -
int newLineSprite ( int x1, int y1, int x2, int y2 )

Arguments:

  • x1, x2: The coordinates of the line's starting point.
  • x2, y2: The coordinates of the line's ending point.

Rectangle Sprite

To create a rectangle sprite, use the "newRectangleSprite" function.

- Function Format -
int newRectangleSprite ( int x, int y, int width, int height, bool fill )

Arguments:

  • x, y: The coordinates of the top-left corner.
  • width, height: The width and height of the rectangle.
  • fill: Set to true to fill the rectangle, or false to draw only the border.

Ellipse Sprite

To create an ellipse sprite, use the newEllipseSprite function.

- Function Format -
int newEllipseSprite ( int x, int y, int width, int height, bool fill )

Arguments:

  • x, y: Coordinates of the top-left corner of the bounding box.
  • width, height: Size of the bounding box.
  • fill: Set to true to fill the ellipse, or false to draw only the border.

The ellipse is drawn to fit inside the specified rectangle.

Polygon Sprite

To create a polygon sprite, use the "newPolygonSprite" function.

- Function Format -
int newPolygonSprite ( int x[ ], int y[ ], bool fill )

Arguments:

  • x[], y[]: Arrays containing the coordinates of the polygon's vertices.
  • fill: Set to true to fill the polygon, or false to draw only the border.

Polyline Sprite

To create a polyline sprite, use the "newPolylineSprite" function.

- Function Format -
int newPolylineSprite ( int x[ ], int y[ ] )

Arguments:

  • x[], y[]: Arrays containing the coordinates of the polyline's vertices.

Text Sprite

To create a text sprite, use the "newTextSprite" function.

- Function Format -
int newTextSprite ( int x, int y, int lineWidth, int lineHeight, string text )

Arguments:

  • x, y: Coordinates of the starting point of the text, aligned with the underline. The origin (0, 0) is at the top-left of the screen, with the X-axis increasing to the right and the Y-axis downward.
  • lineWidth, lineHeight: The maximum width of each line and the spacing between lines. If the text exceeds the line width, it will automatically wrap to the next line.
  • text: The string to be displayed.

Setting the Font Size

To change the font size used in a text sprite, use the "setSpriteFontSize" function.

- Function Format -
void setSpriteFontSize ( int spriteID, int fontSize )

Arguments:

  • spriteID: The ID of the text sprite.
  • fontSize: The font size in pt (points), a common unit for specifying font dimensions.

The "pt" unit is widely used for font sizing. Typically, 12pt is considered a standard readable size. Fonts around 10pt will appear smaller, while 15pt will look slightly larger.

Note that the exact number of pixels per point can vary depending on the environment. While the difference is usually not dramatic, it's not uncommon for text to shift by a few pixels. For this reason, when placing text within a layout, it's recommended to allow for slight variation in positioning rather than relying on exact pixel-perfect alignment.

Image Sprite

To create an image sprite, use the newImageSprite function.

- Function Format -
int newImageSprite (
  int x, int y, int width, int height, int graphicsID
)

Arguments:

  • x, y: Coordinates of the top-left corner where the image will be drawn.
  • width, height: The size of the image.
  • graphicsID: The ID of the graphics resource to draw.

The "graphicsID" can be obtained using "newGraphics(string fileName)" function from the Graphics library to load an image file, or by rendering to another graphics resource using a different renderer.

Example Program

Let's try using the sprite-related functions covered above. Write and run the following code:

Note: If you're using an image sprite, place a PNG file named Test.png in the same folder as the program before running it. Click here to download the sample image.


import Graphics;
import Graphics2D;
import GUI;

// Create a graphics resource and a renderer
int graphicsID = newGraphics( );
int rendererID = newGraphics2DRenderer( 800, 600, graphicsID );

// Create the display window
int windowID = newWindow( 0, 0, 800, 600, " Hello 2DCG ! " );
int labelID = newImageLabel( 0, 0, 800, 600, graphicsID );
mountComponent( labelID, windowID );

// Set background color to white and clear the screen
setGraphics2DColor( rendererID, 255, 255, 255, 255 );
clearGraphics2D( rendererID );



// =========================
// Drawing section starts here
// =========================


// Create a red line sprite from (0, 0) to (100, 100)
int lineSpriteID = newLineSprite( 0, 0, 100, 100 );
setSpriteColor( lineSpriteID, 255, 0, 0, 255 );
mountSprite( lineSpriteID, rendererID );


// Create a blue filled rectangle at (100, 100), size 500 x 300
int rectSpriteID = newRectangleSprite( 100, 100, 500, 300, true );
setSpriteColor( rectSpriteID, 0, 0, 255, 255 );
mountSprite( rectSpriteID, rendererID );


// Create a green filled ellipse at (100, 100), size 500 x 300
int ovalSpriteID = newEllipseSprite( 100, 100, 500, 300, true );
setSpriteColor( ovalSpriteID, 0, 255, 0, 255 );
mountSprite( ovalSpriteID, rendererID );


// Prepare vertex arrays for polygon and polyline
int x[ 3 ];
x[ 0 ] = 100;
x[ 1 ] = 300;
x[ 2 ] = 300;

int y[ 3 ];
y[ 0 ] = 100;
y[ 1 ] = 100;
y[ 2 ] = 300;


// Create a filled yellow polygon sprite
int pgSpriteID = newPolygonSprite( x, y, true );
setSpriteColor( pgSpriteID, 255, 255, 0, 255 );
mountSprite( pgSpriteID, rendererID );


// Create a red polyline sprite
int plSpriteID = newPolylineSprite( x, y );
setSpriteColor( plSpriteID, 255, 0, 0, 255 );
mountSprite( plSpriteID, rendererID );


// Create a black text sprite at (300, 50)
string text = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
int txtSpriteID = newTextSprite( 300, 50, 250, 35, text );
setSpriteColor( txtSpriteID, 0, 0, 0, 255 );
setSpriteFontSize( txtSpriteID, 30 );
mountSprite( txtSpriteID, rendererID );


// Load image from "Test.png" and create an image sprite
int graphicsID2 = newGraphics( "Test.png" );
int imSpriteID = newImageSprite( 350, 100, 300, 200, graphicsID2 );
mountSprite( imSpriteID, rendererID );


// =========================
// Drawing section ends here
// =========================


// Render the registered sprites onto the graphics resource
paintGraphics2D( rendererID );

// Render to the display screen
paintComponent( labelID );
paintComponent( windowID );
Sample.vcssl

When you run this program, a white window will appear with various shapes and content drawn on it.

Execution Result

Note: The font used for rendering text may vary depending on your environment. If you want to specify a font explicitly, use the "setSpriteFont(int spriteID, string fontName)" function.



Sponsored Link



Japanese English
Index
News From RINEARN
* VCSSL is developed by RINEARN.

VCSSL 3.4.52 Released: Enhanced Integration with External Programs and More
2025-05-25 - This update introduces enhancements to the external program integration features (e.g., for running C-language executables). Several other improvements and fixes are also included. Details inside.

Released: Latest Version of VCSSL with Fixes for Behavioral Changes on Java 24
2025-04-22 - VCSSL 3.4.50 released with a fix for a subtle behavioral change in absolute path resolution on network drives, introduced in Java 24. Details inside.

Released the Latest Versions of RINEARN Graph and VCSSL - Now Supporting Customizable Tick Positions and Labels!
2024-11-24 - Starting with this update, a new "MANUAL" tick mode is now supported, allowing users to freely specify the positions and labels of ticks on the graph. We'll explain the details and how to use it.

Released Exevalator 2.2: Now Compatible with TypeScript and Usable in Web Browsers
2024-10-22 - The open-source expression evaluation library, Exevalator, has been updated to version 2.2. It now supports TypeScript and can be used for evaluating expressions directly in web browsers. Explains the details.

Behind the Scenes of Creating an Assistant AI (Part 1: Fundamental Knowledge)
2024-10-07 - The first part of a series on how to create an Assistant AI. In this article, we introduce the essential knowledge you need to grasp before building an Assistant AI. What exactly is an LLM-based AI? What is RAG? And more.

Launching an Assistant AI to Support Software Usage!
2024-09-20 - We've launched an Assistant AI that answers questions about how to use RINEARN software and helps with certain tasks. Anyone with a ChatGPT account can use it for free. We'll explain how to use it.

Software Updates: Command Expansion in RINEARN Graph, and English Support in VCSSL
2024-02-05 - We updated our apps. This updates include "Enhancing the Command-Line Features of RINEARN Graph" and "Adding English Support to VCSSL." Dives into each of them!

Inside the Repetitive Execution Speedup Impremented in Vnano Ver.1.1
2024-01-17 - Delves into the update in Vnano 1.1 from a developer's viewpoint, providing detailed insights into the specific improvements made to the internal structure of the script engine.