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:

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:

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.