emulator/opengl/host/include/libOpenglRender/render_api.h

/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _OPENGL_RENDERER_RENDER_API_H
#define _OPENGL_RENDERER_RENDER_API_H

/* This header and its declarations must be usable from C code.
 *
 * If RENDER_API_NO_PROTOTYPES is #defined before including this header, only
 * the interface function pointer types will be declared, not the prototypes.
 * This allows the client to use those names for its function pointer variables.
 *
 * All interfaces which can fail return an int, with zero indicating failure
 * and anything else indicating success.
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdlib.h>
#include "render_api_platform_types.h"

#if defined(RENDER_API_NO_PROTOTYPES)
#define DECL(ret, name, args) \
	typedef ret (* name##Fn) args
#else
#define DECL(ret, name, args) \
	typedef ret (* name##Fn) args ; \
	ret name args
#endif

/* initLibrary - initialize the library and tries to load the corresponding
 *     GLES translator libraries. This function must be called before anything
 *     else to ensure that everything works. If it returns an error, then
 *     you cannot use the library at all (this can happen under certain
 *     environments where the desktop GL libraries are not available)
 */
DECL(int, initLibrary, (void));

/* list of constants to be passed to setStreamMode */
#define STREAM_MODE_DEFAULT   0
#define STREAM_MODE_TCP       1
#define STREAM_MODE_UNIX      2
#define STREAM_MODE_PIPE      3

/* Change the stream mode. This must be called before initOpenGLRenderer */
DECL(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().
 */
DECL(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().
 */
DECL(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().
 */
typedef void (*OnPostFn)(void* context, int width, int height, int ydir,
                         int format, int type, unsigned char* pixels);
DECL(void, setPostCallback, (OnPostFn onPost, void* onPostContext));

/* createOpenGLSubwindow -
 *     Create a native subwindow which is a child of 'window'
 *     to be used for framebuffer display.
 *     Framebuffer will not get displayed if a subwindow is not
 *     created.
 *     x,y,width,height are the dimensions of the rendering subwindow.
 *     zRot is the rotation to apply on the framebuffer display image.
 */
DECL(int, 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.
 */
DECL(int, destroyOpenGLSubwindow, (void));

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

/* repaintOpenGLDisplay -
 *    causes the OpenGL subwindow to get repainted with the
 *    latest framebuffer content.
 */
DECL(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.
 */
DECL(int, stopOpenGLRenderer, (void));

#ifdef __cplusplus
}
#endif

#endif