package bogue

  1. Overview
  2. Docs

Module Bogue.Sdl_areaSource

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
Sourcetype t
Sourceval 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.

Sourceval update : t -> unit

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

Sourceval clear : t -> unit

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

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

Sourceval 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.

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

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

Sourceval 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).

Sourceval 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.

Sourceval fill_rectangle : t -> color:Draw.color -> w:int -> h:int -> (int * int) -> unit
Sourceval 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.

Sourceval 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.

Sourcetype draw_element
Sourceval 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.

Sourceval disable : draw_element -> unit

Mark an element for skipping its execution.

Sourceval enable : draw_element -> unit

See disable.

Sourceval remove_element : t -> draw_element -> unit

Remove the draw_element from the command queue.

Sourceval add_element : t -> draw_element -> unit

Append the element to the end of the command queue.

Sourceval has_element : t -> draw_element -> bool

Check whether the element belongs to the command queue.

Direct access to the texture

Sourceval get_texture : t -> Tsdl.Sdl.texture option
Sourceval set_texture : t -> Tsdl.Sdl.texture -> unit
OCaml

Innovation. Community. Security.