Implement Palette Swapping

Add a new Pal, PalDisplay and PalReset functions.

Pal replaces color with another one for all subsequent drawings (it is changing the so-called draw palette).

PalDisplay replaces color with another one for the whole screen at the end of a frame (it is changing the so-called display palette).

PalReset resets all swapped colors for all palettes.

Author: elgopher

README.md

@@ -55,7 +55,7 @@ See also [examples](examples) directory and [documentation](https://pkg.go.dev/g
   * [x] drawing sprites and pixels with camera and clipping support
   * [x] add the ability to directly access pixels on the screen and sprite-sheet
   * [x] palette transparency
-  * [ ] palette swapping
+  * [x] palette swapping
   * [ ] printing text on the screen
   * [ ] drawing shapes
     * [ ] lines, rectangles, circles, ovals

ebitengine.go

@@ -69,7 +69,7 @@ func (e *ebitengineGame) replaceScreenPixels(screen *ebiten.Image) {
 
 	offset := 0
 	for _, col := range ScreenData {
-		rgb := Palette[col]
+		rgb := Palette[displayPalette[col]]
 		e.screenDataRGBA[offset] = rgb.R
 		e.screenDataRGBA[offset+1] = rgb.G
 		e.screenDataRGBA[offset+2] = rgb.B

examples/hello/main.go

@@ -7,7 +7,6 @@ import (
 	"github.com/elgopher/pi"
 )
 
-// Go compiler will automatically add sprite sheet to binary
 //go:embed sprite-sheet.png
 var resources embed.FS
 

examples/pal/main.go

@@ -0,0 +1,62 @@
+// Example showing practical use of palette swapping. Drawing same sprite with different palette
+// generates tens of different sprites.
+package main
+
+import (
+	"embed"
+
+	"github.com/elgopher/pi"
+)
+
+//go:embed sprite-sheet.png
+var resources embed.FS
+
+var (
+	eyeColors   = [...]byte{0, 1, 3, 4, 12}
+	skinColors  = [...]byte{7, 5, 15}
+	hairColors  = [...]byte{0, 4, 5, 6, 7, 9, 10}
+	mouthColors = [...]byte{2, 8}
+)
+
+const (
+	eyes  = 1 // color number of eyes in sprite-sheet
+	skin  = 7
+	mouth = 8
+	hair  = 5
+)
+
+func draw() {
+	pi.Cls()
+	x, y := 0, 0
+
+	for _, eyeColor := range eyeColors {
+		pi.Pal(eyes, eyeColor)
+
+		for _, skinColor := range skinColors {
+			pi.Pal(skin, skinColor)
+
+			for _, hairColor := range hairColors {
+				pi.Pal(hair, hairColor)
+
+				for _, mouthColor := range mouthColors {
+					pi.Pal(mouth, mouthColor)
+					// draw the sprite with swapped colors:
+					pi.Spr(0, x, y)
+
+					x += 8
+					if x >= 128 {
+						// go to next line
+						x = 0
+						y += 8
+					}
+				}
+			}
+		}
+	}
+}
+
+func main() {
+	pi.Resources = resources
+	pi.Draw = draw
+	pi.RunOrPanic()
+}

examples/pal/sprite-sheet.png

@@ -125,6 +125,7 @@ func Boot() error {
 	Clip(0, 0, scrWidth, scrHeight)
 	Camera(0, 0)
 	PaltReset()
+	PalReset()
 
 	return nil
 }

pi.go

@@ -74,7 +74,7 @@ func Pset(x, y int) {
 		return
 	}
 
-	ScreenData[y*scrWidth+x] = Color
+	ScreenData[y*scrWidth+x] = drawPalette[Color]
 }
 
 // Pget gets a pixel color on the screen.
@@ -266,7 +266,7 @@ func SprSizeFlip(n, x, y int, w, h float64, flipX, flipY bool) {
 				continue
 			}
 
-			ScreenData[screenOffset+j] = col
+			ScreenData[screenOffset+j] = drawPalette[col]
 		}
 		screenOffset += scrWidth
 		spriteSheetOffset += spriteSheetStep
@@ -289,3 +289,37 @@ var defaultTransparency = [256]bool{true}
 func PaltReset() {
 	colorIsTransparent = defaultTransparency
 }
+
+var drawPalette [256]byte
+
+// Pal replaces color with another one for all subsequent drawings (it is changing
+// the so-called draw palette).
+//
+// Affected functions are Pset, Spr, SprSize and SprSizeFlip.
+func Pal(color byte, replacementColor byte) {
+	drawPalette[color] = replacementColor
+}
+
+var displayPalette [256]byte
+
+// PalDisplay replaces color with another one for the whole screen at the end of a frame
+// (it is changing the so-called display palette).
+func PalDisplay(color byte, replacementColor byte) {
+	displayPalette[color] = replacementColor
+}
+
+// PalSecondary
+
+var notSwappedPalette [256]byte
+
+func init() {
+	for i := 0; i < 256; i++ {
+		notSwappedPalette[i] = byte(i)
+	}
+}
+
+// PalReset resets all swapped colors for all palettes.
+func PalReset() {
+	drawPalette = notSwappedPalette
+	displayPalette = notSwappedPalette
+}

screen.go

@@ -80,12 +80,44 @@ func BenchmarkSprSizeFlip(b *testing.B) {
 	})
 }
 
+func BenchmarkPalt(b *testing.B) {
+	runBenchmarks(b, func(res Resolution) {
+		for i := 0; i < 100; i++ { // Palt is too fast
+			pi.Palt(byte(i), true)
+		}
+	})
+}
+
 func BenchmarkPaltReset(b *testing.B) {
-	for i := 0; i < b.N; i++ {
-		runBenchmarks(b, func(res Resolution) {
+	runBenchmarks(b, func(res Resolution) {
+		for i := 0; i < 100; i++ { // PaltReset is too fast
 			pi.PaltReset()
-		})
-	}
+		}
+	})
+}
+
+func BenchmarkPal(b *testing.B) {
+	runBenchmarks(b, func(res Resolution) {
+		for i := 0; i < 100; i++ { // Pal is too fast
+			pi.Pal(byte(i), byte(i+1))
+		}
+	})
+}
+
+func BenchmarkPalDisplay(b *testing.B) {
+	runBenchmarks(b, func(res Resolution) {
+		for i := 0; i < 100; i++ { // PalDisplay is too fast
+			pi.PalDisplay(byte(i), byte(i+1))
+		}
+	})
+}
+
+func BenchmarkPalReset(b *testing.B) {
+	runBenchmarks(b, func(res Resolution) {
+		for i := 0; i < 100; i++ { // PalReset is too fast
+			pi.PalReset()
+		}
+	})
 }
 
 type Resolution struct{ W, H int }

screen_bench_test.go

@@ -158,6 +158,31 @@ func TestPset(t *testing.T) {
 			})
 		}
 	})
+
+	t.Run("should draw swapped color", func(t *testing.T) {
+		pi.ScreenWidth = 1
+		pi.ScreenHeight = 1
+		pi.BootOrPanic()
+		pi.Color = 1
+		pi.Pal(1, 2)
+		// when
+		pi.Pset(0, 0)
+		// then
+		assert.Equal(t, []byte{2}, pi.ScreenData)
+	})
+
+	t.Run("should draw original color after PalReset", func(t *testing.T) {
+		pi.ScreenWidth = 1
+		pi.ScreenHeight = 1
+		pi.BootOrPanic()
+		pi.Color = 1
+		pi.Pal(1, 2)
+		pi.PalReset()
+		// when
+		pi.Pset(0, 0)
+		// then
+		assert.Equal(t, []byte{1}, pi.ScreenData)
+	})
 }
 
 func TestPget(t *testing.T) {
@@ -478,6 +503,33 @@ func testSpr(t *testing.T, spr func(spriteNo int, x int, y int)) {
 		expectedScreen := decodePNG(t, "internal/testimage/spr_1_on_top_of_2_trans_50.png")
 		assert.Equal(t, expectedScreen.Pixels, pi.ScreenData)
 	})
+
+	t.Run("should swap color", func(t *testing.T) {
+		pi.SpriteSheetWidth, pi.SpriteSheetHeight = 8, 8
+		pi.ScreenWidth, pi.ScreenHeight = 8, 8
+		pi.BootOrPanic()
+		const originalColor byte = 7
+		const replacementColor byte = 15
+		pi.Sset(5, 5, originalColor)
+		pi.Pal(originalColor, replacementColor)
+		// when
+		spr(0, 0, 0)
+		// then
+		actual := pi.Pget(5, 5)
+		assert.Equal(t, replacementColor, actual)
+	})
+
+	t.Run("should draw original color after reset", func(t *testing.T) {
+		boot(8, 8, spriteSheet16x16)
+		expectedScreen := decodePNG(t, "internal/testimage/spr_0_at_00.png")
+		// when
+		pi.Pal(1, 3)
+		pi.Pal(28, 30)
+		pi.PalReset()
+		spr(0, 0, 0)
+		// then
+		assert.Equal(t, expectedScreen.Pixels, pi.ScreenData)
+	})
 }
 
 func TestSprSize(t *testing.T) {