Audio is a major missing feature in Pixel. The time has come to fix this. This issue serves as a design and implementation discussion place as well as progress reporting place.

Requirements

Here, I will summarize the most important requirements I demand from the implementation of an audio system in Pixel.

• Playing sound and music files
• Playing arbitrary generated stream of PCM samples
• Support and preference of streaming, even from files
• Ability to stop the playback at any time
• Easily play arbitrary number of sounds simultaneously
• Playback must be smooth, without glitches and as precise in timing as possible
• Ability to create arbitrary stream-based audio effects in the library as well as by the user of the library (= defining 1 or 2 interfaces for this)

Design

Let's define two abstract interfaces with no specific definitions yet:

1. Wave generator - an object of this type is capable of generating a stream of PCM waves
2. Wave receiver - an object of this type is capable of receiving a stream of PCM waves and acting accordingly

Examples: A loaded sound file is a wave generator. A speaker is a wave receiver, since it receives the waves and plays them. An audio effect is both receiver and generator: it receives waves, modifies them and generates the modified waves.

Having defined these interfaces, here are a few example of ways the user would chain them together to create the final audio result. Objects sending to the right are generators and objects receiving from the left are receivers.

[ clap.mp3 ] -> [ volume adjustment, 0.5x ] -> [ speaker ]
[ sine wave generator ] -> [ distortion effect ] -> [ phaser effect ] -> [ speaker ]
[ music.wav ] -> [speaker ]

The "wave generator" and "wave receiver" names can and probably will change.

Implementation

This is not decided yet. Here are a few examples of possible implementation, all of which are a bit problematic.

1.

type WaveGenerator interface {
    Generate(format Format, p []byte) (n int, err error)
}

type WaveReceiver interface {
    Receive(format Format, p []byte) (n int, err error)
}

I don't like this implementation. For a stream of PCM waves, it requires the user to actively feed the speaker with new data each frame. This would be very hard to use, we would probably implement more abstractions on top of this.

2.

type WaveGenerator interface {
    Generate(format Format, p []byte) (n int, err error)
}

type WaveReceiver interface {
    Receive(WaveGenerator)
    Update()
}

The way you would use this implementation is like this:

sound := loadSound("hello.mp3") // WaveGenerator
effect.Receive(sound)
speaker.Receive(effect)

for !win.Closed() {
    speaker.Update()
}

This way, it'd be easy to create arbitrary chains of generators/receivers, however, questions and problems arise when we ask: How to play multiple sounds together? How to stop the playback? How to play two sounds one after another?

What needs to be done

First, we need to find an actual design that meets all of the requirements. Then we need to implement it.

Low level stuff

For the actual audio playback, we'll use the awesome oto package by @hajimehoshi, which supports audio playback on all major platforms.

Hey guys, thank you all for sticking around!

In the last few months, it has become increasingly more clear that I am no longer able to maintain this repository. Pixel is and always will be one of my favorite projects and my proudest achievements. It was my first (and biggest) open-source success and brought me immense joy and satisfaction. Despite this, my focus and interests have shifted over time to other things and I can no longer gather enough motivation to sustainably maintain the project.

That's why we're looking for a new maintainer. It should be someone, who:

1. Is a good programmer and is experienced with the Go programming language.
2. Has (or wants to have) a passion for Pixel.
3. Is willing to spend time responding to issues, merging pull requests, or perhaps sometimes proposing, designing and implementing new features.
4. Is willing to make new releases and announce them on Reddit, or other platforms.

In other words, someone who wants to take good care of Pixel ;)

If you think you could be this new maintainer, write a reply to this issue.

The new maintainer will become fully responsible for the repository, I will not interfere with their decisions, but I will always be available for discussions, questions, mostly regarding the general direction of the project. If the new maintainer decides to open a Github Sponsors profile, 100% of the money will go to the new maintainer.

Once a new maintainer is in place, Pixel will enter a new phase, hopefully, a very prosperous one :P

That's all, hope we find somebody soon enough!

Hi @faiface Good day! I am a graphic designer/open source enthusiast and i would like to contribute by offering you a logo design which I think will add more to the project's visibility. It is free and i would be glad to do it of course with your permission.Thanks and best regards! - Tobaloidee

OS: Win 10 Go: 1.9

EDIT: This panic is more general than we had imagined, it will occur if you minimize the application in any way (clicking on the minimize icon, Alt+TAB'ing, clicking on the icon on the taskbar), regardless of the windowed/fullscreen state. Comments up until the issue name change imply this is a fullscreen-only issue, which it is not.

If you (for example) make the Platformer example fullscreen then Alt+TAB, it will panic with the following:

panic: reflect: slice index out of range

goroutine 1 [running, locked to thread]:
reflect.Value.Index(0x539120, 0xc0423ecd20, 0x97, 0x0, 0x539120, 0x2, 0xc042c09cf8)
        C:/tools/go/src/reflect/value.go:871 +0x1eb
PixelBugTest/vendor/github.com/go-gl/gl/v3.3-core/gl.Ptr(0x539120, 0xc0423ecd20, 0x539120)
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/go-gl/gl/v3.3-core/gl/conversions.go:44 +0xe4
PixelBugTest/vendor/github.com/faiface/glhf.NewTexture(0x0, 0x0, 0x0, 0x691f98, 0x0, 0x0, 0x0)
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/glhf/texture.go:47 +0x125
PixelBugTest/vendor/github.com/faiface/glhf.NewFrame(0x0, 0x0, 0x0, 0x0)
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/glhf/frame.go:37 +0x75
PixelBugTest/vendor/github.com/faiface/pixel/pixelgl.(*GLFrame).SetBounds.func1()
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/pixel/pixelgl/glframe.go:35 +0x8b
PixelBugTest/vendor/github.com/faiface/mainthread.Call.func1()
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/mainthread/mainthread.go:64 +0x2d
PixelBugTest/vendor/github.com/faiface/mainthread.Run(0x58dbd0)
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/mainthread/mainthread.go:46 +0xf8
PixelBugTest/vendor/github.com/faiface/pixel/pixelgl.Run(0x58dbd0)
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/pixel/pixelgl/run.go:32 +0x60
main.main()
        C:/Users/username/go/src/PixelBugTest/vendor/github.com/faiface/pixel/examples/platformer/main.go:394 +0x34
exit status 2

The error is possibly occurring in the glhf library, and I can confirm that it also happens in my personal project.

1. Adding a Reset method on *text.Text would allow us to not having to do this:

txt.Clear()
txt.Dot = txt.Orig

2. Adding a Printf(format string, a ...interface{}) (n int, err error) method on *text.Text would allow users of the github.com/faiface/pixel/text package to not directly import fmt

3. I'd also like us to consider adding a default atlas (text.BasicAtlas) initialized by:

var BasicAtlas = NewAtlas(basicfont.Face7x13, ASCII)

I believe that doing these changes to the text package would make it more convenient to use. Do you agree @faiface?

Currently, Pixel doesn't support drawing text. This needs to be changed. Implementing text drawing in Go is actually way simpler than I thought it would be.

First of all, there's an awesome package https://godoc.org/golang.org/x/image/font, which implements standard font face interface, which is well designed and very useful. Subpackages implement several font types and https://godoc.org/github.com/golang/freetype/truetype implements TrueType font loading with support of the standard font face interface. So we've got all we need.

Now, the design of text drawing in Pixel.

Text drawing should be done in a not-yet-existing "github.com/faiface/pixel/text" package. This package should export (at least) one type: Text. Creating one should be done by text.New(face), where face is a font.Face value. The *Text value returned from New will use that specific font face.

Text type should implement io.Writer interface, so drawing text to it is as simple as fmt.Sprintf(txt, "hello world"). Printing to Text draws text "to the Text object". To draw the printed text to another target (such as a window, canvas, batch, ...), simply use txt.Draw(target). Clearing needs to be supported too (txt.Clear()).

Drawing text needs to be fast. There should be no problem drawing a full screen of random text using a tiny font face at 60 FPS without a performance hit. This is something that many other libraries fail to accomplish, but it's actually not very hard. It's easily achievable by caching glyphs.

So, to recap the interface.

• "github.com/faiface/pixel/text"
  • New(font.Face) *Text
  • type Text
    • Clear()
    • Draw(pixel.Target)
    • Write(b []byte) (n int, err error)

This is the basis for the interface. More methods will probably be added, such as WriteString, or SetDot (the position of the text line).

Hey, first of all really nice game library, I like it how easy it's to work with it and the fact that is based on opengl. I'm interested to find out if this library will be GUI compatible in the near future...currently there isn't a stable gui library for go, but I do believe that this library could make a good one ;)

Hello Michal,

first let me tell you that this is a very cool game library that you have created! In the past I have created a lot of little games and other programs in Go, I even have my own little game library which does a very similar job but has not as many features as yours.

The next Ludum Dare is coming up and I wanted to try using someone else's engine. Looking through the options I found yours very delightful, especially your little gopher game :-)

In order to get to know your engine in preparation, I ported my last Ludum Dare entry to it. This pull request is mainly to let you know about it (I know how cool it is to see others use your creations) and to say thank you for your effort to create something cool for the open source and especially the Go community! I would love to see a lot more games and desktops apps written in Go.

A second reason for this PR is that I am very proud of my little game and I think it is great fun so I want to share it with people. Your examples are basically demos to show one or two features of your library in action. The gopher platformer is the closest to a real game. Even though my game is not large or really sophisticated, it is a complete game with graphics, audio, menus, instructions, fun gameplay and high scores. I think it makes for a great addition to your example list for people to see what is possible and to have a "real-life" example of how to use both your pixel and beep libraries.

Again, you are doing a great job here, keep up the good work!

PS: I am also working on a big addition to your library, I will create another pull request when that is done... :-)

When I use .Polygon(0) (e.g. fill) and have a complex figure the fill does not just fill the area but also (on the left side?) it colors outside the lines... When switching to .Polygon(1) I have the correct figure, but the lines are not crisp, it seems the line thickness is perpendicular with the actual line. Now the lines seems "hairy" when I zoom in.

Is there a way to only fill the designated area defined by a closed set of points?

http://www.glfw.org/docs/3.1/input.html#cursor_mode

Mainly implemented to allow window-based mouse locking, but should (and does) support all other cursor modes as well.

This PR adds the concept of anchors to align elements.

It adds:

• type Anchor: a vector used to define anchors, such as Center, Top, TopRight, etc.;
• func (Anchor) String() string: returns the string representation of an anchor.;
• func (*Rect) AnchorPos(anchor Anchor) Vec: returns the ~~absolute~~ position of the given anchor of the Rect.;
• ~~edit: func (*Rect) AnchorTo(Anchor): updates the Rect position to align it on the given anchor.~~
• edit: func (Rect) AlignedTo(Anchor) Rect: returns the rect moved to be aligned on the given anchor.
• ~~edit: func (Matrix) Aligned(Rect, anchorPos AnchorPos) Matrix: moves everything to align the given rectangle on the given anchor position.~~
• edit: func (*Text) AlignedTo(pixel.Anchor) *Text: returns the text moved by the given anchor.
• edit: func (Anchor) Opposite() Anchor: returns the opposite position of the anchor (ie. Top -> Bottom; BottomLeft -> TopRight, etc.).

Example code

edit: Update with last modifications.

package main

import (
	"image/color"
	"fmt"
	"github.com/faiface/pixel"
	"github.com/faiface/pixel/imdraw"
	"github.com/faiface/pixel/pixelgl"
	"golang.org/x/image/colornames"
	"github.com/faiface/pixel/text"
	"golang.org/x/image/font/basicfont"
)

const (
	winWidth   float64 = 600
	winHeight  float64 = 450
	padding    float64 = 170
	rectWidth, rectHeight float64 = 90, 90
	minX, minY float64 = padding, padding
	maxX, maxY float64 = winWidth - padding, winHeight - padding
	cX, cY     float64 = winWidth/2, winHeight/2
)

var dotsPos map[pixel.Anchor]pixel.Vec = map[pixel.Anchor]pixel.Vec{
	pixel.Center: pixel.V(cX, cY),
	pixel.Top: pixel.V(cX, maxY),
	pixel.TopRight: pixel.V(maxX, maxY),
	pixel.Right: pixel.V(maxX, cY),
	pixel.BottomRight: pixel.V(maxX, minY),
	pixel.Bottom: pixel.V(cX, minY),
	pixel.BottomLeft: pixel.V(minX, minY),
	pixel.Left: pixel.V(minX, cY),
	pixel.TopLeft: pixel.V(minX, maxY),
}
func drawRectanglesAndDots(win *pixelgl.Window) {
	imd := imdraw.New(nil)
	for anchor, vect := range dotsPos {
		rect := pixel.R(vect.X, vect.Y, vect.X + rectWidth, vect.Y + rectHeight).AlignedTo(anchor)
		drawRect(imd, rect, colornames.Gray)
		drawDot(imd, vect, colornames.Red)
	}
	imd.Draw(win)
}

func drawLabels(win *pixelgl.Window) {
	const scale float64 = 2
	basicAtlas := text.NewAtlas(basicfont.Face7x13, text.ASCII)
	for anchor, vect := range dotsPos {
		basicTxt := text.New(vect, basicAtlas)
		basicTxt.Color = colornames.Yellow
		fmt.Fprintln(basicTxt, anchor.String())
		basicTxt.AlignedTo(anchor).Draw(win, pixel.IM.Scaled(basicTxt.Orig, scale))
	}
}

func drawRect(imd *imdraw.IMDraw, rect pixel.Rect, color color.Color) {
	imd.Color = color
	imd.Push(rect.Min, rect.Max)
	imd.Rectangle(0)
}

func drawDot(imd *imdraw.IMDraw, vect pixel.Vec, color color.Color) {
	imd.Color = color
	imd.Push(vect)
	imd.Ellipse(pixel.V(3, 3), 0)
}

func run() {
	cfg := pixelgl.WindowConfig{
		Title:  "AnchorPos examples",
		Bounds: pixel.R(0, 0, winWidth, winHeight),
		VSync:  true,
	}
	win, err := pixelgl.NewWindow(cfg)
	if err != nil {
		panic(err)
	}

	win.Clear(colornames.Lightgray)
	drawRectanglesAndDots(win)
	drawLabels(win)

	for !win.Closed() {
		win.Update()
	}
}

func main() {
	pixelgl.Run(run)
}

Result

More to come

edit: done!

~~The modifications added in this first commit are required for other functions that I plan to add as well in this PR, named AnchorTo:~~

~~- func (r *Rect) AnchorTo(anchor AnchorPos): updates the Rect position to align it on the given anchor.~~ ~~- func (r *Text) AnchorTo(anchor AnchorPos): updates the Text position to align it on the given anchor.~~ ~~- etc. At this point it's easy to add implementation for many other objects (Circle, Image, etc.)~~

~~Example usage:~~

basicTxt := text.New(vect, basicAtlas)
basicTxt.AnchorTo(AnchorPos.Center)

~~Here, basicTxt will be centered relative to the vect position. With AnchorPos.Left, it will be centered verticaly but not horizontally, etc.~~

~~This is helpful to position and align elements.~~

~~I would like to get your feedback before to continue. ;)~~

Hello. It is possible to set letter spacing? I mean analog letter-spacing.

Example code

func main() {
   ttf, err := loadTTF("Mariupol-Regular.ttf", 8) //function from doc
   if err != nil {
	 log.Fatal(err)
   }
   
   atlas := text.NewAtlas(ttf, text.ASCII, text.RangeTable(unicode.Cyrillic))
   basicTxt := text.New(pixel.V(15, 175), atlas)
   basicTxt.SetKerning(2) //I want to use something similar, but I can't find it in the pixel or freetype/truetype
}

when i run final code of this part of tutorial animation lags in places

which led me to think that this behavior would also be in the game that I want to make so I chose to use other game engine

until I found #304 and ran the command: go get -u -tags=gles3 github.com/go-gl/glfw/v3.3/glfw after that, the problem is solved and the animation is always smooth it turns out it was because I have apple arm cpu

i think it is important to mention that problem and command to solve it in tutorial or other documentation so that some people don't get wrong impression about the engine when they go through tutorial

First, I'd like to just say thank you for this package. I've been using Pixel for a few months now, and I'm very happy with it. It has the perfect balance between simplicity and not trying too hard to isolate me away the underlying logic.

As my game is growing in size and complexity, I often find it challenging to deal with the fact that SetMatrix (in many components) actually makes the component stateful, which in some situations makes it harder to have clean separate of concerns.

At the same time, I've met other challenges due to the fact that not all components have the same definition: Sometimes it's Draw(target) and sometimes it's Draw(target, matrix). As go is very strictly typed, there is no convenient solution to make all components compatible with a single Drawer interface.

Is there a fundamental and purposeful design difference between those two patterns?

target.SetMatrix(matrix)
foo.Draw(target)

foo.Draw(target, matrix)

If no, do you think that making everything use the second pattern would be a welcome change to this package?

I added shaders to my game recently and to ease in the new feature I decided to use your passthrough shader from the tutorial here. After adding it, I noticed anything being drawn by an IMDraw was black instead of the color it was supposed to be. Sprites and the Canvas clear color all show up as normal, but my IMDraw borders around buttons and simplistic progress bar appear as black.

Two causes come to mind.

1. There is no "texture" for IMDraw things for the shader to reference.
2. I'm drawing everything to a canvas, and then drawing the canvas to the window.

Number 1 makes a lot of sense if you look at the source, but I don't think I know enough about shaders yet to know what to do instead. Number 2 is something I read can enable a lot of advanced things but I'm still wrapping my head around the details so I admit this might be a side effect of that.

I don't think this is a bug in pixel, just in my understanding. How should I write my shaders to work with IMDraw?

Mac Big Sur x64 Pixel v0.10 Go 1.17.7

Currently, it appears that we're only intended to ever use one fragment shader, and uniforms are only updated once per frame.

A little reworking should permit multiple shaders to be used / switched between, and for uniforms to be changed between draw calls, which would allow much greater flexibility in applying different effects to different graphical elements in a scene.