render.pl

    1/*  Part of the SDL3 pack for SWI-Prolog.
    2
    3    SDL_render.h — 2D hardware-accelerated renderer, textures, drawing.
    4
    5    @see https://wiki.libsdl.org/SDL3/SDL_render
    6*/
    7
    8:- module(sdl_render, [
    9    sdl_createrenderer/3,
   10    sdl_setrendervsync/2,
   11    sdl_destroyrenderer/1,
   12    sdl_renderclear/1,
   13    sdl_rendertexture/4,
   14    sdl_renderpresent/1,
   15    sdl_createtexturefromsurface/3,
   16    sdl_createtexture/6,
   17    sdl_destroytexture/1,
   18    sdl_setrenderdrawcolor/5,
   19    sdl_renderrect/2,
   20    sdl_renderfillrect/2,
   21    sdl_updatetexture/4,
   22    sdl_locktexture/4,
   23    sdl_unlocktexture/1,
   24    sdl_texture_access/2
   25]).   26
   27:- use_module(library(sdl/foreign), [
   28    sdl_createrenderer_/3,
   29    sdl_setrendervsync_/2,
   30    sdl_destroyrenderer/1,
   31    sdl_renderclear/1,
   32    sdl_rendertexture_/4,
   33    sdl_renderpresent/1,
   34    sdl_createtexturefromsurface_/3,
   35    sdl_createtexture_/6,
   36    sdl_destroytexture/1,
   37    sdl_setrenderdrawcolor_/5,
   38    sdl_renderrect_/2,
   39    sdl_renderfillrect_/2,
   40    sdl_updatetexture_/4,
   41    sdl_locktexture_/4,
   42    sdl_unlocktexture_/1,
   43    sdl_renderer_blob_portray/2,
   44    sdl_texture_blob_portray/2
   45]).   46:- reexport(library(sdl/foreign), [
   47    sdl_destroyrenderer/1,
   48    sdl_renderclear/1,
   49    sdl_renderpresent/1,
   50    sdl_destroytexture/1
   51]).   52:- use_module(library(sdl/pixels), [sdl_pixel_format/2]).   53:- use_module(library(sdl/surface)).   % for sdl_surface_blob type
   54:- use_module(library(ptr)).   55
   56:- multifile error:has_type/2.   57error:has_type(sdl_renderer_blob, X) :- blob(X, sdl_renderer_blob).
   58error:has_type(sdl_texture_blob,  X) :- blob(X, sdl_texture_blob).
   59error:has_type(sdl_texture_access, X) :- sdl_texture_access(X, _).
   60
   61:- multifile prolog:error_message//1.   62prolog:error_message(type_error(sdl_renderer_blob, Culprit)) -->
   63   [ 'sdl_renderer_blob, found ~q'-[Culprit] ].
   64prolog:error_message(type_error(sdl_texture_blob, Culprit)) -->
   65   [ 'sdl_texture_blob, found ~q'-[Culprit] ].
   66prolog:error_message(type_error(sdl_texture_access, Culprit)) -->
   67   { findall(F, sdl_texture_access(F, _), Fs) },
   68   [ 'sdl_texture_access (one of ~q), found ~q'-[Fs, Culprit] ].

sdl_renderclear(+Renderer:blob) is det

Clear the current rendering target with the drawing color.

See also: - https://wiki.libsdl.org/SDL3/SDL_RenderClear

sdl_renderpresent(+Renderer:blob) is det

Present the rendered frame to the screen.

See also: - https://wiki.libsdl.org/SDL3/SDL_RenderPresent

sdl_destroyrenderer(+Renderer:blob) is det

Destroy a previously created renderer blob.

See also: - https://wiki.libsdl.org/SDL3/SDL_DestroyRenderer

sdl_destroytexture(+Texture:blob) is det

Destroy a previously created texture blob.

See also: - https://wiki.libsdl.org/SDL3/SDL_DestroyTexture

   94user:portray(Renderer) :-
   95   blob(Renderer, sdl_renderer_blob), !,
   96   sdl_renderer_blob_portray(current_output, Renderer).
   97user:portray(Texture) :-
   98   blob(Texture, sdl_texture_blob), !,
   99   sdl_texture_blob_portray(current_output, Texture).

sdl_createrenderer(-Renderer:blob, +Window:blob, +Name:term) is det

Create a 2D hardware-accelerated renderer for the given window. Name selects the driver (null for the default) or a string naming a driver.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateRenderer

  108sdl_createrenderer(Renderer, Window, Name) :-
  109   must_be(var, Renderer),
  110   must_be(sdl_window_blob, Window),
  111   must_be((oneof([null]) ; string), Name),
  112   sdl_createrenderer_(Renderer, Window, Name).

sdl_setrendervsync(+Renderer:blob, +VSync:integer) is det

Toggle the renderer's vsync synchronization. VSync is 0 (off), 1 (on) or a negative value for "late" vsync.

See also: - https://wiki.libsdl.org/SDL3/SDL_SetRenderVSync

  121sdl_setrendervsync(Renderer, VSync) :-
  122   must_be(sdl_renderer_blob, Renderer),
  123   must_be(integer, VSync),
  124   sdl_setrendervsync_(Renderer, VSync).

sdl_createtexturefromsurface(-Texture:blob, +Renderer:blob, +Surface:blob) is det

Create a texture from an existing surface blob.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateTextureFromSurface

  132sdl_createtexturefromsurface(Texture, Renderer, Surface) :-
  133   must_be(var, Texture),
  134   must_be(sdl_renderer_blob, Renderer),
  135   must_be(sdl_surface_blob, Surface),
  136   sdl_createtexturefromsurface_(Texture, Renderer, Surface).

sdl_rendertexture(+Renderer:blob, +Texture:blob, +Srcrect:term, +Dstrect:term) is det

Draw a texture to the renderer. Each of Srcrect and Dstrect is null for the corresponding full region, or a term rect(X, Y, W, H).

See also: - https://wiki.libsdl.org/SDL3/SDL_RenderTexture

  145sdl_rendertexture(Renderer, Texture, Srcrect, Dstrect) :-
  146   must_be(sdl_renderer_blob, Renderer),
  147   must_be(sdl_texture_blob, Texture),
  148   maplist(
  149      must_be((compound(rect(number, number, number, number)) ; oneof([null]))),
  150      [Srcrect, Dstrect]),
  151   sdl_rendertexture_(Renderer, Texture, Srcrect, Dstrect).

sdl_setrenderdrawcolor(+Renderer:blob, +R:between(0,255), +G:between(0,255), +B:between(0,255), +A:between(0,255)) is det

Set the color used by sdl_renderrect/2 and sdl_renderfillrect/2.

See also: - https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawColor

  159sdl_setrenderdrawcolor(Renderer, R, G, B, A) :-
  160   must_be(sdl_renderer_blob, Renderer),
  161   must_be(between(0, 255), R),
  162   must_be(between(0, 255), G),
  163   must_be(between(0, 255), B),
  164   must_be(between(0, 255), A),
  165   sdl_setrenderdrawcolor_(Renderer, R, G, B, A).

sdl_renderrect(+Renderer:blob, +Rect:rect) is det

Draw a rectangle outline. Rect is a term rect(X, Y, W, H) of numbers.

See also: - https://wiki.libsdl.org/SDL3/SDL_RenderRect

  173sdl_renderrect(Renderer, Rect) :-
  174   must_be(sdl_renderer_blob, Renderer),
  175   must_be(compound(rect(number, number, number, number)), Rect),
  176   sdl_renderrect_(Renderer, Rect).

sdl_renderfillrect(+Renderer:blob, +Rect:rect) is det

Draw a filled rectangle. Rect is a term rect(X, Y, W, H) of numbers.

See also: - https://wiki.libsdl.org/SDL3/SDL_RenderFillRect

  184sdl_renderfillrect(Renderer, Rect) :-
  185   must_be(sdl_renderer_blob, Renderer),
  186   must_be(compound(rect(number, number, number, number)), Rect),
  187   sdl_renderfillrect_(Renderer, Rect).

sdl_texture_access(?Access:atom, ?Value:integer) is nondet

Texture access patterns.

static
streaming
target

See also: - https://wiki.libsdl.org/SDL3/SDL_TextureAccess

  198% --- texture access enum ----------------------------------------------------
  199
  200sdl_texture_access(static, 0).
  201sdl_texture_access(streaming, 1).
  202sdl_texture_access(target, 2).

sdl_createtexture(-Texture:blob, +Renderer:blob, +Format:sdl_pixel_format, +Access:sdl_texture_access, +Width:positive_integer, +Height:positive_integer) is det

Create a texture. Format is one of the atoms enumerated by sdl_pixel_format/2 and Access one of the atoms enumerated by sdl_texture_access/2.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateTexture

  212% --- create texture ---------------------------------------------------------
  213
  214sdl_createtexture(Texture, Renderer, Format, Access, Width, Height) :-
  215   must_be(var, Texture),
  216   must_be(sdl_renderer_blob, Renderer),
  217   must_be(sdl_pixel_format, Format),
  218   must_be(sdl_texture_access, Access),
  219   must_be(positive_integer, Width),
  220   must_be(positive_integer, Height),
  221   sdl_pixel_format(Format, IntFormat),
  222   sdl_texture_access(Access, IntAccess),
  223   sdl_createtexture_(Texture, Renderer, IntFormat, IntAccess, Width, Height).

sdl_updatetexture(+Texture:blob, +Rect:term, +Pixels:ptr_blob, +Pitch:integer) is det

Update a texture with new pixel data from a PtrBlob, avoiding creating/destroying a texture every frame when streaming dynamically rendered content (e.g. cairo). Rect is null for the entire texture, or a term rect(X, Y, W, H).

See also: - https://wiki.libsdl.org/SDL3/SDL_UpdateTexture

  234sdl_updatetexture(Texture, Rect, Pixels, Pitch) :-
  235   must_be(sdl_texture_blob, Texture),
  236   must_be((compound(rect(number, number, number, number)) ; oneof([null])), Rect),
  237   must_be(ptr_blob, Pixels),
  238   must_be(integer, Pitch),
  239   sdl_updatetexture_(Texture, Rect, Pixels, Pitch).

sdl_locktexture(+Texture:blob, +Rect:term, -Pixels:ptr, -Pitch:integer)

is det.

Lock a texture so it can be updated. On success Pixels is a PtrBlob to the locked region and Pitch its row stride. Rect is null for the whole texture, or a term rect(X, Y, W, H). Use sdl_unlocktexture/1 when done.

See also: - https://wiki.libsdl.org/SDL3/SDL_LockTexture

  250sdl_locktexture(Texture, Rect, Pixels, Pitch) :-
  251   must_be(sdl_texture_blob, Texture),
  252   must_be((compound(rect(number, number, number, number)) ; oneof([null])), Rect),
  253   must_be(var, Pixels),
  254   must_be(var, Pitch),
  255   sdl_locktexture_(Texture, Rect, Pixels, Pitch).

sdl_unlocktexture(+Texture:blob) is det

Unlock a texture previously locked with sdl_locktexture/4.

See also: - https://wiki.libsdl.org/SDL3/SDL_UnlockTexture

  263sdl_unlocktexture(Texture) :-
  264   must_be(sdl_texture_blob, Texture),
  265   sdl_unlocktexture_(Texture)