Direct Drawing - Revision history

Dcurrent at 04:35, 16 August 2026

2026-08-16T04:35:46Z

← Older revision		Revision as of 00:35, 16 August 2026
Line 746:		Line 746:
	* [[Openborvariant]]		* [[Openborvariant]]
	* [[Sprites]]		* [[Sprites]]
			[[Category:Openbor]]
			[[Category:Graphics]]
			[[Category:Script]]

Dcurrent: /* Limits and performance */

2026-08-16T03:58:20Z

Limits and performance

← Older revision		Revision as of 23:58, 15 August 2026
Line 725:		Line 725:
	Sprite loading and screen allocation are setup operations, not frame-by-frame drawing operations. Reusing allocations avoids file access, decoding work, heap churn, and leak risk.		Sprite loading and screen allocation are setup operations, not frame-by-frame drawing operations. Reusing allocations avoids file access, decoding work, heap churn, and leak risk.

	Large subscreens cost memory and fill bandwidth, but a completed surface consumes only one sprite-queue entry when submitted with <code>drawscreen()</code>, ~~allowing~~ subscreens to act as sprite queue multipliers. Keep off-screen surfaces near the size of the content being composed, use widths divisible by four, and redraw only when their contents need to change.		Large subscreens cost memory and fill bandwidth, but a completed surface consumes only one sprite-queue entry when submitted with <code>drawscreen()</code>. In effect, subscreens act as sprite-queue multipliers by consolidating many separately drawn elements into a single queued item. Keep off-screen surfaces near the size of the content being composed, use widths divisible by four, and redraw only when their contents need to change.

	== Practical guidance ==		== Practical guidance ==

Dcurrent: /* Limits and performance */

2026-08-16T03:55:19Z

Limits and performance

← Older revision		Revision as of 23:55, 15 August 2026
Line 725:		Line 725:
	Sprite loading and screen allocation are setup operations, not frame-by-frame drawing operations. Reusing allocations avoids file access, decoding work, heap churn, and leak risk.		Sprite loading and screen allocation are setup operations, not frame-by-frame drawing operations. Reusing allocations avoids file access, decoding work, heap churn, and leak risk.

	Large subscreens cost memory and fill bandwidth, but a completed surface consumes only one sprite-queue entry when submitted with <code>drawscreen()</code>. Keep off-screen surfaces near the size of the content being composed, use widths divisible by four, and redraw only when their contents need to change.		Large subscreens cost memory and fill bandwidth, but a completed surface consumes only one sprite-queue entry when submitted with <code>drawscreen()</code>, allowing subscreens to act as sprite queue multipliers. Keep off-screen surfaces near the size of the content being composed, use widths divisible by four, and redraw only when their contents need to change.

	== Practical guidance ==		== Practical guidance ==

Dcurrent: /* drawdot */

2026-08-16T03:50:46Z

drawdot

← Older revision		Revision as of 23:50, 15 August 2026
Line 437:		Line 437:
	Each queued dot occupies one sprite-queue entry, but the 5,000-entry queue provides generous headroom. The 80-step curve above submits only 81 dots, and ordinary curves, outlines, particles, or object-heavy gameplay remain comfortably within practical capacity.		Each queued dot occupies one sprite-queue entry, but the 5,000-entry queue provides generous headroom. The 80-step curve above submits only 81 dots, and ordinary curves, outlines, particles, or object-heavy gameplay remain comfortably within practical capacity.

	Subscreens are still valuable for persistent drawings or deliberately dense raster work. Use <code>drawdottoscreen()</code> to generate static procedural artwork once, retain it on a subscreen, then place the completed surface with <code>drawscreen()</code>. ~~This recommendation is primarily about avoiding unnecessary regeneration, not treating~~ the ~~sprite queue as a scarce resource~~.		Subscreens are still valuable for persistent drawings or deliberately dense raster work. Use <code>drawdottoscreen()</code> to generate static procedural artwork once, retain it on a subscreen, then place the completed surface with <code>drawscreen()</code>.
			[[File:World Hereos Timeless Sine.png\|none\|frame\|An example of creating shapes with dots. Calculating a sine wave and drawing as rows of single pixels with color graduation produces the smoothly curved line shown here.]]

	=== drawline ===		=== drawline ===

Dcurrent at 03:43, 16 August 2026

2026-08-16T03:43:03Z

Show changes

Dcurrent: /* Dimensions and anchors */

2026-08-16T03:03:52Z

Dimensions and anchors

← Older revision		Revision as of 23:03, 15 August 2026
Line 337:		Line 337:

	Sprite anchor values can shift the visible image relative to <code>x</code> and <code>y</code>. Subtracting <code>centerx</code> and <code>centery</code> from the draw coordinates produces the visible image's upper-left position.		Sprite anchor values can shift the visible image relative to <code>x</code> and <code>y</code>. Subtracting <code>centerx</code> and <code>centery</code> from the draw coordinates produces the visible image's upper-left position.
			[[File:Dragons of Rage Rescaled.png\|none\|frame\|The red boxes seen are script drawn sprite borders. Sprite profiling is useful for a huge variety of effects - one example might be randomized fire sparks around a character when suffering from burn attacks.]]

	==== Pixel format ====		==== Pixel format ====

Dcurrent: /* Syntax */

2026-08-16T02:51:00Z

Syntax

Show changes

Dcurrent: /* Inspecting a sprite */

2026-08-16T02:32:05Z

Inspecting a sprite

Show changes

Dcurrent: /* loadsprite */

2026-08-16T02:31:43Z

loadsprite

← Older revision		Revision as of 22:31, 15 August 2026
Line 121:		Line 121:
	=== loadsprite ===		=== loadsprite ===

	~~{{Function~~		<syntaxhighlight lang="c" line="1">
	~~\|name = loadsprite~~
	~~\|parameters = path, maskpath~~
	~~\|returns = Sprite pointer or empty value~~
	~~\|description = Loads an image as a script-owned sprite. The optional mask image supplies transparency data.~~
	}}

	<syntaxhighlight lang="c">
	void sprite = loadsprite("data/sprites/interface/marker.gif");		void sprite = loadsprite("data/sprites/interface/marker.gif");
	void masked = loadsprite("data/sprites/interface/glow.gif",		void masked = loadsprite("data/sprites/interface/glow.gif",

Dcurrent: /* loadsprite */

2026-08-16T02:11:42Z

loadsprite

← Older revision		Revision as of 22:11, 15 August 2026
Line 121:		Line 121:
	=== loadsprite ===		=== loadsprite ===

	<syntaxhighlight lang="c~~" line="1~~">		{{Function
			\|name = loadsprite
			\|parameters = path, maskpath
			\|returns = Sprite pointer or empty value
			\|description = Loads an image as a script-owned sprite. The optional mask image supplies transparency data.
			}}

			<syntaxhighlight lang="c">
	void sprite = loadsprite("data/sprites/interface/marker.gif");		void sprite = loadsprite("data/sprites/interface/marker.gif");
	void masked = loadsprite("data/sprites/interface/glow.gif",		void masked = loadsprite("data/sprites/interface/glow.gif",
Line 127:		Line 134:
	</syntaxhighlight>		</syntaxhighlight>

	~~Each call creates~~ a ~~separate sprite outside the normal sprite cache~~. Load reusable artwork once during setup instead of loading it ~~every frame~~.		<code>loadsprite()</code> places the requested image under OpenBOR's resource management and returns a script-owned handle. Load reusable artwork once during setup, retain the returned pointer, and reuse it for every frame that needs the artwork. Repeatedly loading and freeing the same file abuses the intended resource lifecycle and should be avoided.

			<code>free()</code> tells OpenBOR that the script no longer needs the handle. The engine may release active sprite and mask data while retaining internal resource records and previously allocated cache capacity. This retention is deliberate and beneficial: it lets OpenBOR recognize and intelligently reuse sprite resources instead of blindly repeating every lookup, allocation, and load operation.

			Memory reserved for those records and caches does not necessarily disappear immediately after <code>free()</code>. Rapid load/free cycles can expand the retained high-water capacity and make misuse look like a memory leak. That appearance does not indicate a defect in the resource manager - it indicates that short-lived loading is defeating a system designed around reuse.

			Treat loaded sprites as retained resources rather than disposable draw commands. Load each sprite once, reuse it as needed, then call <code>free()</code> when its useful lifetime truly ends.

	Transparent borders are trimmed while the sprite is prepared. Internal offsets preserve the visible artwork's position relative to the X and Y values passed to a draw function. Mask artwork should match the source image's dimensions and transparent layout.		Transparent borders are trimmed while the sprite is prepared. Internal offsets preserve the visible artwork's position relative to the X and Y values passed to a draw function. Mask artwork should match the source image's dimensions and transparent layout.