Module Useri.Surface

module Surface: sig .. end

Rendering surface.

An application has a single rendering surface that is specified by a Useri.Surface.t value given to Useri.App.init.

Surface mode

See also surface mode information in the `Jsoo backend.

type mode = [ `Fullscreen | `Windowed ]

The type for surface modes.

val mode : mode React.signal

mode is the application's surface mode. The value of this signal is defined by the ~mode argument of the surface given to Useri.App.init, the occurences of the event specified by Useri.Surface.set_mode_setter and external events.

val set_mode_setter : mode React.event -> unit

set_mode_setter me uses occurences of me to set, if possible, the current surface's application mode and the value of Useri.Surface.mode.

val mode_flip : 'a React.event -> mode React.event

mode_flip e is an event which occur whenever e does with the opposite mode of Useri.Surface.mode's value.

val pp_mode : Format.formatter -> mode -> unit

pp_mode ppf m prints an unspecified representation of m on ppf.

Surface specification

See also surface specification information inf the `Jsoo backend.

module Gl: sig .. end

The type for OpenGL surface specification.

type handle = Useri_base.Surface.handle

The type for backend dependent surface handles.

type kind = [ `Gl of Gl.t | `Other ]

The type for surface kinds.

type t

The type for surface specification.

val create : ?hidpi:bool ->
       ?pos:Gg.p2 ->
       ?size:Gg.size2 ->
       ?kind:kind ->
       ?handle:handle ->
       ?mode:mode -> unit -> t

create hidpi pos size kind anchor mode () is a surface specification with:

hidpi, if true (default) tries to get a high-dpi surface.
pos, a hint to position the surface by using pos as the position of the top-left corner of the surface in its backend dependent display container. The coordinates of the top-left corner of the display container is (0,0) and coordinate increase in from top to bottom and left to right.
size, the size of the surface in logical pixels. Consult the individual backend documentation for the default value.
kind is the kind of surface.
handle is a backend dependent surface handle. In certain backends allows to interface Useri with pre-existing surfaces.
mode is the the surface mode.

Note. Currently the size and pos arguments are specified The actual raster size of the surface is in the Useri.Surface.raster_size signal. Note that future versions of this library will switch to physical dimensions (lack of backend support is the problem at the moment).

Application Surface

See also information about surface properties updates in the `Jsoo backend.

Warning. These values and functions are defined only after Useri.App.init was called.

val pos : Gg.p2 React.signal

pos is the position of the top-left corner of the surface in the surface's backend dependent display container.

val raster_size : Gg.size2 React.signal

raster_size is the application's surface underlying raster size.

val size : Gg.size2 React.signal

size is the application's surface logical size.

val update : unit -> unit

update () updates the rendering surface. This has to be called for your drawing commands to be taken into account.

val handle : unit -> Useri_base.Surface.handle

handle () is the application's surface backend dependent handle.

Refreshing surfaces

These events are for coordinating rendering in an energy efficient manner. See Input, animation and rendering coordination for more information.

val refresh : float React.event

refresh occurs whenever the surface needs to be redrawn with the number of seconds since its last occurence or, for the first occurence, the number of seconds since the application start.

The exact occurence frequency is unspecified but generally it should not exceed the hinted frequency of Useri.Surface.refresh_hz hertz.

More precisely the following occurences are guaranteed:

Some time after the Useri.Surface.size signal changes value (including the first time during Useri.App.init).
Some time after an occurence of the event set by Useri.Surface.set_refresher.
Some time after a call to Useri.Surface.request_refresh.
Some time after a Useri.Time.count or Useri.Time.unit signal is created or updates.

Useri guarantees that this event doesn't occur simultaneously with any of the events or signal it exposes.

val request_refresh : unit -> unit

request_refresh () has the effect of making Useri.Surface.refresh occur some time after it was called. This function call is cheap and can be abused (can be called in a React step).

Warning. This function may be removed from the API in the future.

val set_refresher : 'a React.event -> unit

set_refresher r uses sets r to be used to generate an occurence of Useri.Surface.refresh some time after each occurence of r.

val steady_refresh : until:'a React.event -> unit

steady_refresh until makes Useri.Surface.refresh occur at the hinted frequency of Useri.Surface.refresh_hz hertz until until occurs.

val refresh_hz : int React.signal

refresh_hz is the maximal hinted frequency in hertz for Useri.Surface.refresh occurences. The initial value is 60.

val set_refresh_hz : int -> unit

set_refresh_hz sets the value of Useri.Surface.refresh_hz.