!render_api

%#include "render_api_platform_types.h"
%#include <stdbool.h>
%#include <stddef.h>
%#include <stdint.h>

%typedef void (*OnPostFn)(void* context, int width, int height, int ydir,
%                         int format, int type, unsigned char* pixels);

# Initialize the library and tries to load the corresponding EGL/GLES
# translation libraries. Must be called before anything else to ensure that
# everything works. Returns 0 on success, error code otherwise.
# If it returns an error, you cannot use the library at all.
int initLibrary(void);

# Change the stream mode. This must be called before initOpenGLRenderer()
# |mode| is one of STREAM_DEFAULT, STREAM_UNIX, STREAM_TCP or STREAM_PIPE.
int setStreamMode(int mode);


# initOpenGLRenderer - initialize the OpenGL renderer process.
#
# width and height are the framebuffer dimensions that will be reported to the
# guest display driver.
#
# addr is a buffer of addrLen bytes that will receive the address that clients
# should connect to. The interpretation depends on the transport:
#   - TCP: The buffer contains the port number as a string. The server is
#     listening only on the loopback address.
#   - Win32 and UNIX named pipes: The buffer contains the full path clients
#     should connect to.
#
# This function is *NOT* thread safe and should be called first
# to initialize the renderer after initLibrary().
int initOpenGLRenderer(int width, int height, char* addr, size_t addrLen);

# getHardwareStrings - describe the GPU hardware and driver.
# The underlying GL's vendor/renderer/version strings are returned to the
# caller. The pointers become invalid after a call to stopOpenGLRenderer().
void getHardwareStrings(const char** vendor, const char** renderer, const char** version);

# A per-frame callback can be registered with setPostCallback(); to remove it
# pass NULL for both parameters. While a callback is registered, the renderer
# will call it just before each new frame is displayed, providing a copy of
# the framebuffer contents.
#
# The callback will be called from one of the renderer's threads, so will
# probably need synchronization on any data structures it modifies. The
# pixels buffer may be overwritten as soon as the callback returns; if it
# needs the pixels afterwards it must copy them.
#
# The pixels buffer is intentionally not const: the callback may modify the
# data without copying to another buffer if it wants, e.g. in-place RGBA to
# RGB conversion, or in-place y-inversion.
#
# Parameters are:
#   context        The pointer optionally provided when the callback was
#                  registered. The client can use this to pass whatever
#                  information it wants to the callback.
#   width, height  Dimensions of the image, in pixels. Rows are tightly
#                  packed; there is no inter-row padding.
#   ydir           Indicates row order: 1 means top-to-bottom order, -1 means
#                  bottom-to-top order.
#   format, type   Format and type GL enums, as used in glTexImage2D() or
#                  glReadPixels(), describing the pixel format.
#   pixels         The framebuffer image.
#
# In the first implementation, ydir is always -1 (bottom to top), format and
# type are always GL_RGBA and GL_UNSIGNED_BYTE, and the width and height will
# always be the same as the ones passed to initOpenGLRenderer().
void setPostCallback(OnPostFn onPost, void* onPostContext);

# createOpenGLSubwindow -
#     Create a native subwindow which is a child of 'window'
#     to be used for framebuffer display.
#     x,y,width,height are the dimensions of the rendering subwindow.
#     zRot is the rotation to apply on the framebuffer display image.
#
#     Return true on success, false on failure, which can happen when using
#     a software-only renderer like OSMesa. In this case, the client should
#     call setPostCallback to get the content of each new frame when it is
#     posted, and will be responsible for displaying it.
bool createOpenGLSubwindow(FBNativeWindowType window, int x, int y, int width, int height, float zRot);

# destroyOpenGLSubwindow -
#   destroys the created native subwindow. Once destroyed,
#   Framebuffer content will not be visible until a new
#   subwindow will be created.
#   Return true on success, false otherwise.
bool destroyOpenGLSubwindow(void);

# setOpenGLDisplayRotation -
#    set the framebuffer display image rotation in units
#    of degrees around the z axis
void setOpenGLDisplayRotation(float zRot);

# repaintOpenGLDisplay -
#    causes the OpenGL subwindow to get repainted with the
#    latest framebuffer content.
void repaintOpenGLDisplay(void);

# stopOpenGLRenderer - stops the OpenGL renderer process.
#     This functions is#NOT* thread safe and should be called
#     only if previous initOpenGLRenderer has returned true.
int stopOpenGLRenderer(void);