Drawing Primitives in Land
The most basic information drawing primitives need is, where on the target should they be drawn. There are several ways:
Relative screen coordinates. For example, 0/0 is the upper left screen edge, 1/1 the lower right screen edge. A rectangle from 0.1/0.1 to 0.9/0.9 would span 80% of the width and the height of the screen, and leave a 10% border all around. Obviously, using such coordinates is most useful if you don’t want to care at all about the actual resolution used.
Pixel coordinates. A coordinate is given in pixels. So, if you draw a line from 1/1 to 2/2, the pixels at 1/1 and at 2/2 would be lit. This is what Land originally used in its first incarnation, a very long time ago. This has some disadvantages. Besides positions relying on the current resolution, it is also impossible to specify sub-pixel behavior, for example when anti-aliasing is switched on.
Subpixel coordinates. This is what Land uses by default, but you can easily change it. It is a mixture of the two modes above. You give coordinates in pixel positions (so positions depend on the resolution), but each integer position is the upper left corner of a pixel, not the pixel as a whole, as in the method before. To get the behavior of the previous method, you would do two things:
For rectangles, draw them with their full width.
For images, don’t do anything.
To make clear why, let’s compare a rectangle and an image. The rectangle is drawn at pixel 0/0 with the pixel method, and 10x10 pixels big. So the pixels that are lit are from 0/0 to 9/9, inclusive. Doing the same with the subpixel method, we would draw a rectangle from 0/0 to 10/10.
But what just happened? The rectangle of lit pixels before was 10x10 pixels big, from pixel 0 to pixel 9 inclusive. The new subpixel rectangle also is 10x10 pixels big. Just now there is no more inclusive/exclusive pixels, the rectangle coordinates are independent now.
The problem is, that what we really want with subpixel coordinates is not just an outline anymore, but a frame which is one pixel thick. Its outer rectangle would actually start at 0/0, and end at 10/10. Its inner rectangle would start at 1/1 and end at 9/9. Drawing a single rectangle from 0.5/0.5 to 9.5/9.5 just works, because we assumed a line-thickness of 1.
But with images, there is no line thickness. So if we draw an image which is 10x10 pixels big, and we draw it to 0/0, it will exactly fit the same rectangle. Would we draw it to 0.5/0.5, that just would be wrong.
Now, to make things easier, you don’t have to use sub-pixel coordinates if you absolutely don’t want to. Call:
land_use_screen_positions()
to use the method which maps the screen to 0/0..1/1,
or
land_use_pixel_positions()
to use pixel positions. That is, Land will always lit the exact pixel you specify, and also draw images correctly to full-pixel positions. In fact, this mode just maps the coordinates like described above, so you still can use non-integer positions (but there really is no reason to not use one of the other two positioning modes then) and enable e.g. anti-aliasing.
This draws a line from the first point to the second point.
This draws a rectangle from the first point to the second point.
Like rectangle, but filled.
This draws a circle, inscribed into the given rectangle. The alternate names “ellipse” and “oval” for this function actually fit better.
Like circle, but filled.
Parameters: int w, int h, int flags
Returns: LandDisplay*
Parameters: LandDisplay * self
Parameters: float w, float h, float l, float t, float r, float b, int how
Returns: double
Parameters: float * x, float * y, float * w, float * h
Parameters: float w, float h, int how
no parameters
Returns: LandFloat
Parameters: LandImage * image
Change the display of the current thread to an internal display which draws to the specified image. This cannot be nested.
Restore the display to what it was before the call to land_set_image_display.
Make the active display of the current thread the active one. This may involve creating a new window. There is usually no need to call this function directly, as it will be called internally.
Retrieve a handle to the currently active display of the calling thread.
Make the current display invalid. Usually there is no need for this.
Parameters: double howlong
This function is dangerous! It will completely halt Land for the passed time in seconds. The function will try to determine how long flipping of the display takes. This can be used to see if the refresh rate is honored (usually because vsync is enabled).
Toggle the current thread’s display between windowed and fullscreen mode, if possible.
Parameters: float r, float g, float b, float a
Clear the current thread’s display to the specified color. Always set ’‘’a’’’ to 1, or you may get a transparent background.
Parameters: float z
Change the color of the current thread’s active display. This is the color which will be used for subsequent graphics commands.
Parameters: LandColor c
Returns: LandColor
Parameters: float t
Parameters: float * r, float * g, float * b, float * a
Retrieve the current color.
Parameters: int state
Returns: int
Parameters: float x, float y, float x_, float y_
Parameters: float * cx1, float * cy1, float * cx2, float * cy2
Parameters: float x, float y, float x_, float y_, float a, float a_
Parameters: float x, float y
Parameters: int n, float * xy
Parameters: float x0, float y0, float x1, float y1, float x2, float y2
Parameters: int n, LandFloat * xyzrgb
Parameters: LandImage * image, int n, float * xy, float * uv
Parameters: LandImage * image, int n, float * xy, float * uv, float * rgba
Parameters: int n, float * xy, int * holes
Parameters: int n, float * xy, float * rgba
Parameters: int w, int h
Resize the current display to the given dimensions.
Parameters: int x, int y
Parameters: int * w, int * h
Parameters: char const * title
Parameters: LandImage * icon
Returns: LandImage*
Parameters: LandDisplay * display
Parameters: char const * filename
Parameters: char const * name
Parameters: LandFloat angle
Pre-rotate the current transformation.
Parameters: LandFloat x, LandFloat y
Pre-scale the current transformation.
Pre-translate the current transformation. That is, any transformations in effect prior to this call will be applied afterwards. And transformations after this call until before the next drawing command will be applied before.
Parameters: LandFloat z
Parameters: LandFloat * x, LandFloat * y, LandFloat * z
Parameters: Land4x4Matrix m
Parameters: Land4x4Matrix * matrix
Parameters: int state, int value
When using custom shaders, use this to restore the shader expected by the builtin functions.