1. How to render 2D things

Warning

This page compares 2 possible approaches to 2D rendering in CGE. This page is really not a good introduction into "making 2D games in CGE". For such introduction, instead follow the manual from the beginning, in particular learn about viewports, scenes and how to use them for 2D.

1.1. Full-featured option: Render using a viewport

Use TCastleViewport. Add TCastleViewport control to the window, and inside it draw things by creating TCastleTransform descendants (like TCastleScene, TCastleImageTransform, TCastlePlane).

You should call TCastleViewport.Setup2D on the viewport to make it most natural for 2D games (makes camera orthographic and looking down Z axis, so your 2D world spans in XY). When using the engine editor, use the menu item "Add User Interface → Viewport (2D)" — it adds a TCastleViewport and calls TCastleViewport.Setup2D to configure it.

Read at least these manual chapters:
- Viewport with scenes, camera, navigation introduces the TCastleScene. It is a versatile component that can load models from various file formats. It can play animations. Everything described in viewport and scenes works for 3D and 2D models as well.
- Using TCastleViewport for 2D is documented in designing 2D worlds. We encourage to first familiarize yourself with 3D operations, simply because the 3D tutorial is complete now, and then read designing 2D worlds to learn the differences for 2D.
- Physics documents how to use physics with it.
The engine template "2D game", examples in 2d_games subdirectory, various 2D examples in physics follow this approach.
The important API reference links: TCastleScene, TCastleSceneCore, TCastleViewport.
To render sprites you can load sprite sheets using TCastleScene. You can play it’s animation just like any other scene (use Scene.PlayAnimation method, test with Castle Model Viewer panel "Animations").
To build a geometry from code (without loading it from a model file), you need to create a graph of X3D nodes. Various examples showing it are around the engine, the simpler is http://castle-engine.io/x3d_implementation_geometry2d.php . It instantiates a TRectangle2DNode. One could instead instantiate also TIndexedFaceSetNode which represents a free mesh, with custom texture coordinates and anything else you may need.
To render pixel-art, set texture filtering to "nearest". It’s easiest to do this by setting Scene.RenderOptions.MagnificationFilter := magNearest. Alternatively, you could control this on a particular shape using TTexturePropertiesNode.
You can load image as TCastleImageTransform (more advised) or TCastleScene. See using images.
To have reliable field of view (regardless of the window size in pixels, regardless of UI scaling, regardless of viewport size), set Camera.Orthographic.Width or Camera.Orthographic.Height to non-zero. We advise this, this is usually most natural to control viewport field of view reliably. If you create a 2D viewport in editor, we actually initialize Camera.Orthographic.Width to 1000 now.

If both Camera.Orthographic.Width and Camera.Orthographic.Height are zero then viewport field of view follows window size (adjusted by UI scaling). This is not advised. It means you will have to take more care to display proper content in all cases, in all allowed viewport sizes, window sizes etc.

See the "2D game" new project template for example.
You can use physics in this approach (see various 2D examples in physics).
You can mix 2D and 3D freely. The TCastleViewport.Camera defines projection settings and controls camera. The orthographic camera, TCastleCamera.Orthographic, is usually what you want for 2D games. You can insert a TCastleScene with 3D content to any TCastleViewport, there are no restrictions like "this viewport can only contain 2D content", inside the engine we don’t really have any distinction like "2D content" vs "3D content".
To use shaders, see shaders manual.
- (Recommended) You can add shader effects (to extend existing rendering) using Effect and EffectPart nodes.
  
  To do this in Pascal (setup the nodes in Pascal), see e.g. demos shader_effects_simple, shader_effects_on_shape.
  
  To do this in X3D (editing X3D file), see our demo models, in particular compositing_shaders subdirectory.
- (Not Recommended) You can override standard engine shaders using ComposedShader and ShaderPart nodes. See https://castle-engine.io/x3d_implementation_shaders.php about these X3D nodes.
  
  To do this in Pascal (setup the nodes in Pascal), see demo on examples/shaders/shader_override .
  
  To do this in X3D (editing X3D file), see our demo models, in particular shaders subdirectory.
Activate batching by TCastleViewport.DynamicBatching. It works completely automatically by grouping rendered shapes that use the same material.

Advice when to use:

This approach is most powerful and flexible, so this is the approach we advice now, always.
This approach allows engine to take care of animations, physics, and other cool stuff for you.
All Cat-astrophe Games 2D games ("Dragon Squash", "Escape from the Universe", "The Unholy Society") were implemented using this approach.

1.2. Simple (imperative) option: Render using TDrawableImage

Use TDrawableImage as your main way to draw. In this approach, you create TDrawableImage instance for each image, and then draw it in overridden TCastleUserInterface.Render method. This is the same approach as we use for our 2D user-interface rendering (various TCastleUserInterface instances use it). The main advantage of this approach is simplicity: you just draw 2D images.

A similar approach is to draw your game using multiple TCastleImageControl instances. TCastleImageControl is a simple user-interface control that draws images, using TDrawableImage under the hood, exposing mostly the same features.

Manual:
- Designing user interface and handling events (press, update) within the view documents basic image display using TCastleImageControl.
- User Interface.
- Custom drawn 2D controls shows the "core" of this approach: new TCastleUserInterface descendant with your own Render implementation, in which we call TDrawableImage.Draw.
API reference: TDrawableImage.
You can render sprites using the appropriate TDrawableImage.Draw overload (where you specify which part of the source image to render).

Warning
There’s also a class TSprite (it uses TDrawableImage underneath), but it is deprecated now, please don’t use it.
To render pixel-art, set TDrawableImage.SmoothScaling to false.
Besides TDrawableImage there are also simple drawing helpers like DrawRectangle that are also simple to use.
To have fixed resolution (regardless of the actual window size in pixels), use UI scaling. However, while it scales correctly all the existing TCastleUserInterface instances, you will need to put some additional work to make UI scaling affect your custom TCastleUserInterface descendant. This is documented at the bottom of Advanced: custom drawn 2D controls — basically, look at your ScreenRect and scale all coordinates by UIScale before passing them to TDrawableImage. So the scaling is not hidden from you in this case — you get the information you need, but you need to put some code to make it happen correctly.

To have the scaling automatically applied, you can use TCastleImageControl instead of directly drawing with TDrawableImage. TCastleImageControl is an UI control that wraps TDrawableImage underneath, and allows to control the image like a normal UI control: with anchors, automatically applied scaling and so on.
To use custom shader, set TDrawableImage.CustomShader or TCastleImageControl.CustomShader. Demo in examples/images_videos/image_render_custom_shader.
You can use batching by TDrawableImage.BatchingBegin and TDrawableImage.BatchingEnd. It works completely automatically by grouping rendering the same image many times into one draw call.

Advice when to use: This approach is very easy to start. You have relatively small API to learn. You just learn how to use TDrawableImage, and you draw inside your own TMyControl.Render however you like. If all you really want is a flexible API to draw images — this is it.

2. Why there are 2 approaches to render 2D images/sprites

Because they are both useful :)

Drawing using TDrawableImage is imperative.
Settings things up using TCastleScene is declarative.

The declarative approach is more powerful (the engine can do automatically a lot of more stuff for you, this way).

The imperative stuff is simpler to use, and enough for simple use-cases. I wondered about removing this approach, but it seems many people like it, and it is enough for many use-cases.

3. Can these methods be combined, to render using TDrawableImage within TCastleScene?

I plan to enable rendering using TDrawableImage into a TCastleScene one day. Then you could render user interface into TCastleScene, rotate this TCastleScene, and have easy user-interface in 3D. This is part of roadmap .

To improve this documentation just edit this page and create a pull request to cge-www repository.