Exercises
Welcome to the Arcan Developer Exercises!
These are a series of exercises that intend to help you get perspective as to what Arcan can be used for and how to interpret documentation and debugging tools, how visualization problems can be broken down and approached, and as a means of incrementally get an idea of how the engine works internally.
The exercises have been grouped into three categories, based on their perceived difficulty (i.e. beginner, intermediate, advanced), with an additional 'low level' category for those that already are proficient but want to build more advanced systems or interoperate with the engine on lower levels.
Most exercises can be approached from two perspectives:
-
'Curious', developer that has a graphical application in mind.
-
'Engine Internals', developer that is interested in how the engine works.
For the curious developer, all you need is a working Arcan installation and a text-editor. For engine internals, being comfortable with C and associated developer tools is necessary. It might also be useful to have access to a minimalistic tracer, e.g. APITrace.
Each exercise has a section that is marked based on the intended perspective, and will hint at which calls are relevant, how to navigate the documentation and code and the surrounding tools.
Note that the exercises marked Low Level only target those interested in engine internals and lower system level work (e.g. how to interact with the engine by writing custom frameservers etc).
The sets are still woefully incomplete so a lot of pages are missing, as they are written during short downtime periods. Check the tests/exercises for cheating on solving the problems and for seeing how far the writing has come.
The first exercise introduces you to loading and displaying images, text and single- colored regions, along with first level debugging tools.
The second exercise introduces you to transformation chains: scaling, rotation, blending and how they interact with interpolation.
The third exercise takes care of the necessary evil behind getting access to input devices and the timing sources available.
Exercise 3: Getting Control and keeping Time
The fourth exercise works through how video objects can be connected to each-other and which rules and caveats that apply.
This fifth exercise works though how a video object can be used as a rotating storage that are cycled automatically, for applications e.g. animation.
The sixth exercise takes the first steps towards introducing shaders, how the rendering rules for each video object can be defined programmatically.
The seventh exercise introduces other ways of sharing state and data and builds on the 4th exercise, by adding Null Surfaces and Clones.
The eight exercise goes through how to deal with the details of picking objects, this is rather simple for the curious developer perspective and somewhat painful for the engine internals one.
Exercise 8: Who, What, Where and When
The ninth exercise covers the rather limited set of audio playback features, mainly sample playback and gain control. Later sessions will include source recording and other forms of audio routing.
Now the gloves are coming off as the basics are in place. The first intermediate exercise is that of rendertargets, which cover a key mechanism for off-screen rendering (sometimes called render to texture) that are used for a number of effects and techniques.
Exercise 1: Target for rendering
The second exercise extends the topic on shaders by looking at some engine built-in uniforms, how to define and set your own, and performance considerations.
Exercise 2: 50 Shaders of Grey
The third exercise is the first of several that looks into the concept of frameservers, with a longer description on how they are used and for which purposes.
The fourth exercise concern texture coordinate management, their defaults and what customized coordinate sets can be used for.
The fith exercise is about the context stack, and how it relates to resource management.
Exercise 5: Stacked, Know your Limits
The sixth exercise looks into the, rather basic, set of engine features that can be used for rendering 3D scenes.
Exercise 6: The third Dimensions
The seventh exercise returns to the frameserver concept and shows how recordtargets are used for reading back.
Exercise 7: A record for future generations
The eight exercise looks into the more advanced debugging feature where a special instance of Arcan is run in order to debug itself.
Exercise 8: Monitoring for Change
The first advanced exercise looks into how frameserver connections are made, and the difference between authoritative and non-authoritative connections.
The second exercise looks how an odd but potent combination of engine features can be used to compare frameserver data against older iterations of itself.
The third exercise expands again on the frameserver idea, and covers how additional segments can be requested and (rejected or pushed) to an existing frameserver, and what this is used for.
The fourth exercise covers frameserver state-management, what events to look out for and how state can be explicitly pushed between frameservers.
The fifth exercise covers the special LWA (lightweight-) Arcan build where Arcan can be used as an application engine and as a display server.
The sixth exercise covers the networking modes when it comes to listening for new connection, discovering new servers and so on (for protocol details, see the corresponding Low-Level exercise).
The lower level exercises are more varied and slightly more verbose as they also describe the surrounding reasoning, design decisions, ...
The first exercise walks through how namespace mapping works, which namespaces that are available and how they relate.
The second exercise walks through how the engine is tested and where to add more tests.
The third exercise goes through how to use the shared memory API.
The fourth exercise looks into the PoC hijack library. Exercise 4: Meet Hi-Jack
The fifth exercise continues the practical networking example with a low-level version that details communication protocol, state transfer and discovery.
The sixth exercise looks into the security model along with support facilities for fuzzing.