Welcome to the first exercise set. Here, we will look at how to get access to basic image objects and get an idea of how to use them. Note that this is not written as a finished step-by-step tutorial but rather something slightly more cryptic that provides you with hints and links towards where to look but you are expected to 'solve' the issues yourself.

If you get stuck, solutions will be available in tests/exercises in the source repository. It is assumed that you have an installation that is up and running and some very basic (functions, tables, iterators, conditionals) view of programming in Lua. For a quick syntax rundown of the basics that may be useful here:

function myfun(arg1, ...)
 local ul = 10
 local tbl = {1, 2, 4, 8, 16, 32}

 print(#tbl);
 tbl["can also be non-indexed"] = true
 print(#tbl, "though these are counted differently")

 local sub = function(a, b)
	ul = ul - 1
  return a + b + ul, a - b
 end

-- index starts at 1, default step is +1, evaluation is <=
 for i=1,#tbl-1 do
  print(sub(tbl[i], tbl[i+1], type(tbl[i]))
 end

 for k,v in pairs(tbl) do
  print(k, v)
 end

 for i,v in ipairs(tbl) do
  print(i, v)
 end

 local me
 me = function(i)
  return "hi: " .. tostring(i)
 end

 print(me(12))

-- ul = ul < 0 ? 0 : ul;
 ul = ul < 0 and 0 or ul
end

Each subtask builds upon the previous one, so use / modify the same source code files to speed things up.

The subtasks to go through here are as follows:

Create a Program that displays a full-screen, single color surface, call it exercise1.

Hint 1: Arcan enforces a naming convention, the main folder should have the same name as the desired application name, and there should be at least one file with the same name as the folder (+ the extension .lua). That file should have at least one function (the entrypoint), again named the same as the application name.

Hint 2: All built-in functions have a corresponding .lua file in the doc/ subdirectory, where you can find arguments, description and example of use. There is also a script (mangen) that can generate man-pages from these scripts.

Hint 3: Look for a function called color_surface, note that newly created surfaces start out hidden (use show_image, blend_image), also check the contents of the globals VRESW and VRESH.

Load and show an image specified on the command-line, with error handling.

Hint 1: An indexed table of command-line arguments are passed to the entry-point function as the first argument.

Hint 2: Use warning() and return shutdown() to convery error messages / terminate.

Hint 3: Resource loading is hierarchical, use resource() function to query the availability of a specific resource.

By default, image loading is a synchronous operation. That means that the engine will block and stall until the image has loaded. This is undesirable in more advanced applications. Replace the image-loading from the previous step with the load_image_asynch version.

Hint 1: Look at the example in the documentation for how to use the callback property.

After loading and showing the image, use the system_snapshot() function to generate a dump of your current objects and their internal state. Save one and look at the contents. Make sure that it survives multiple invocations of the same program.

Hint 1: You may need to call zap_resource() if your state-file already exists.

The output should say 'Hello World' with a different color and size for each character and it should be drawn at the center of the screen.

Hint 1: Look into the render_text call for format string options.

Hint 2: The text renderer is stateful, the last loaded font and size will remain active until overridden.

Hint 3: fonts/default.ttf is usually available.

Hint 4: To position the image (move_image) you may need to know its dimensions (image_surface_properties).

Take a look at the difference between drawing the text at an absolute grid position, and at an offset (+0.3).

A quirk that one have to deal with is that arcan can be run in several different contexts: as a display server/windowing system, as a client within an existing window system and as a client to itself.

The last case has a whole lot of nuances to it that will be saved for much later, but the one thing to handle already is that of the window resizing. Not all windowing systems permit graphical clients like this one to just resize, and there might be a conflict resolution needed between the display size that the windowing system wants you to use, the size that you can provide, and the size that is ideal for your contents.

This exercise requires that you run as a client in some other windowing system, X11, Quartz, Wayland and so on. In turn, this requires that arcan is built with a suitable platform, typically sdl2.

Start by implementing an event handler for display_state and print the VRESW and VRESH globals. Resize the window and notice how it changes.