Rework the Texture section in the programming guide #2821

TL;DR: Needs clearer wording, cross-refs, and better organization.

What Needs Work?

https://api.arcade.academy/en/development/programming_guide/textures.html#custom-textures

Wording

Introduction

In https://api.arcade.academy/en/development/programming_guide/textures.html#introduction :

• Choose a better phrase than "sprite engine" (we don't use the word elsewhere in the doc or code base)

There is another texture type in Arcade in the lower level OpenGL API: arcade.gl.Texture2D. This represents an actual OpenGL texture and should only be used when dealing with the low level rendering API.

Textures can be created/loaded before or after the window is created because they don’t interact with OpenGL directly.

• Clearly define the separate texture layers:
  • Software / RAM (Arcade)
  • pyglet
  • OpenGL / The GPU

In https://api.arcade.academy/en/development/programming_guide/textures.html#texture-uniqueness :

When a texture is created a hash/name is required. This should be a unique string. If two more more textures have the same name we will run into trouble.

When loading textures the absolute path to the file is used as part of the name including vertical/horizontal/diagonal, size and other parameter for a truly unique name.

• Add clear definition of the required data
• Explain what "trouble" means
• Explain what "unique" means
  • Cross-reference path handling
  • Briefly clarify the algorithm with a cross-reference to the source file
• Explain the flipping options

Cross-Refs

In https://api.arcade.academy/en/development/programming_guide/textures.html#texture-cache:

• What attribute? Where?
  

• This should cross-ref https://api.arcade.academy/en/development/api_docs/api/cache.html#arcade.cache.TextureCache.flush :