Update render documentation to clarify Stackable vs Renderable types

[lolbinarycat]

code:

fps := render.NewDrawFPS()
render.Draw(fps)

error:

cannot use fps (type *render.DrawFPS) as type render.Renderable in argument to render.Draw:
        *render.DrawFPS does not implement render.Renderable (missing Attach method)

[Patrick Stephen]

This is intended, DrawFPS satisfies the Stackable type. It is currently used as:

render.SetDrawStack(
	render.NewDynamicHeap(),
	render.NewDrawFPS(),
	render.NewLogicFPS(),
)

The justification at the time was that this is moderately more accurate in terms of timing (for DrawFPS at least, less so for LogicFPS) and as debug information it shouldn't intermingle with regular drawn elements.

It could certainly be changed in v3 to be a Renderable. In the meantime the code could be copied into a separate type with a similar draw function.

[Patrick Stephen]

Another justification I recall is that whether the fps counter should be shown tends to be a global setting, not a per-scene setting. If this was a renderable, it would need to be re-created during each scene start.

[lolbinarycat]

Ah, I see. It seems problem then the is a lack of documentation. Nowhere I looked mentioned that, and fps_test.go uses unexported functions.

[Patrick Stephen]

Yeah, https://godoc.org/github.com/oakmound/oak/render#DrawFPS says DrawFPS is a draw stack element but it could be made more explicit

[lolbinarycat]

Ah, but the problem with that is that it expects me to know that refers to fulfilling a specific interface, and not just "thing that is drawn (using a stack)"

[lolbinarycat]

Sorry if that came off as a bit rude, it is hard to write good documentation without an external point of view. I hope I can be some help with that, both in writing and reviewing.

[Patrick Stephen]

Mind if I rename this issue then to "Update render documentation to clarify Stackable vs Renderable types"? No worries about tone, its OK

[lolbinarycat]

Yeah that sounds like a good idea.