bogue 20231209 · OCaml Package

SDL Area widget.

You can use an Sdl_area widget to draw whatever you want using all the power of the SDL renderer API.

Technically, an Sdl_area widget contains an SDL texture and sets it as a render target.

SDL commands are sent to the Sdl_area using add (and stored in a command queue). You can also use add_get in order to get a handle on the command in case you reserve the possibility to remove the command with remove_element.

Dependency graph

type t

val create : 
  width:int ->
  height:int ->
  ?style:Style.t ->
  ?timeout:int ->
  unit ->
  t

Create an empty SDL area. Note that the given size (width,height) is the logical pixel size of the area. The physical size, to be used for most SDL rendering functions, can be obtained with drawing_size.

val update : t -> unit

Force the area to be re-drawn at the next graphics frame.

val clear : t -> unit

Clear the area (this removes all commands from the render queue).

val add : t -> ?name:string -> (Tsdl.Sdl.renderer -> unit) -> unit

add area ~name f adds the arbitrary command f to the render queue. The command should be fast, otherwise it will block the UI when the queue is executed. For long drawings, it's better to split them into many commands. If you need the possibility to remove a command later, use add_get instead.

val cache : t -> unit

This will insert a special command in the queue that will save the texture obtained at that point, and clear all previous commands in the queue. Commands added to the queue after the cache invocation are not removed. Further updates to the area will show the cached texture and then execute the rest of the queue. Use this only for performance reasons when the rendering queue uses a lot of power and/or time.

val clear_cache : t -> unit

Clear the graphics cache generated by the cache command. It has no effect if no cache was created. Clearing the cache does not restore the commands in the queue that were used to draw it.

Drawing functions and utilities

Shortcuts to some drawing functions from the Draw module.

For more sophisticated shapes (and faster rendering), consider using the tsdl_gfx external library or, better, the companion bogue-cairo library.

val drawing_size : t -> int * int

Size in physical pixels of the target SDL texture on which you can draw. You may also use Tsdl.Sdl.get_renderer_output_size, if used inside the Sdl_area command queue.

val pointer_pos : t -> Tsdl.Sdl.event -> int * int

Position of the pointer (mouse or touchscreen that has generated the event) in physical pixels, with respect to the top-left corner of the Sdl_area. Should be called only after the Sdl_area has been rendered.

val to_pixels : (int * int) -> int * int

Convert BOGUE logical coordinates into pixel coordinates usable for the SDL area. Same as Draw.to_pixels.

val draw_line : 
  t ->
  color:Draw.color ->
  thick:int ->
  (int * int) ->
  (int * int) ->
  unit

draw_line c ~color ~thick (x1, y1) (x2, y2) draws a line of given color and thickness from point (x1, y1) to point (x2, y2).

val draw_rectangle : 
  t ->
  color:Draw.color ->
  thick:int ->
  w:int ->
  h:int ->
  (int * int) ->
  unit

draw_rectangle c ~color ~thick ~w ~h x0 y0 draws a rectangle of the given line thickness inside the box of top-left coordinates (x0, y0), width w and height h.

val fill_rectangle : 
  t ->
  color:Draw.color ->
  w:int ->
  h:int ->
  (int * int) ->
  unit

val draw_circle : 
  t ->
  color:Draw.color ->
  thick:int ->
  radius:int ->
  (int * int) ->
  unit

draw_circle c ~color ~thick ~radius (x0, y0) draws a circle of the given line thickness and color inside the disc of center coordinates (x0, y0) and given radius.

An example of draw_circle is provided by Example #50 (it can be run from the terminal with boguex 50), which produces the following picture:

The source code for all boguex examples is here.

val fill_circle : t -> color:Draw.color -> radius:int -> (int * int) -> unit

Draw elements

The command queue can be manipulated. An element of this queue is called a draw_element.

type draw_element

val add_get : 
  t ->
  ?name:string ->
  ?disable:bool ->
  (Tsdl.Sdl.renderer -> unit) ->
  draw_element

Similar to add, but returns the corresponding draw_element. If disable is true, the command will not be executed.

val disable : draw_element -> unit

Mark an element for skipping its execution.

val enable : draw_element -> unit

See disable.

val remove_element : t -> draw_element -> unit

Remove the draw_element from the command queue.

val add_element : t -> draw_element -> unit

Append the element to the end of the command queue.

val has_element : t -> draw_element -> bool

Check whether the element belongs to the command queue.

Direct access to the texture

val get_texture : t -> Tsdl.Sdl.texture option

val set_texture : t -> Tsdl.Sdl.texture -> unit

package bogue

Dependency graph

Drawing functions and utilities

Draw elements

Direct access to the texture