1The renderControl.in file in this directory defines an API which is decoded
2on the android guest into a stream and get decoded and executed on the host.
3It is used in order to query the host renderer as well as send the host renderer
4control commands.
5
6The following describes each of the entries defined by this renderControl API.
7
8
9GLint rcGetRendererVersion();
10       This function queries the host renderer version number.
11
12EGLint rcGetEGLVersion(EGLint* major, EGLint* minor);
13       This function queries the host renderer for the EGL version
14       it supports. returns EGL_FALSE on failure.
15
16EGLint rcQueryEGLString(EGLenum name, void* buffer, EGLint bufferSize);
17       This function queries the host for EGL string (.i.e EGL_EXTENSIONS).
18       if buffer is NULL or the bufferSize is not big enough the return value
19       is the negative number of bytes required to store the string value
20       otherwise the string value is copied to buffer and its size is
21       returned.
22
23EGLint rcGetNumConfigs(uint32_t* numAttribs);
24       queries the host for the number of supported EGL configs.
25       The function returns the number of supported configs and returns in
26       numAttribs the number of attributes available for each config.
27
28EGLint rcGetConfigs(uint32_t bufSize, GLuint* buffer);
29       This function queries the host for the all set of supported configs
30       with their attribute values.
31       bufSize is the size of buffer, the size should be at least equal to
32       (numConfigs + 1) * numAttribs * sizeof(GLuint)
33       where numConfigs and numAttribs are the values returned in
34       rcGetNumConfigs. if bufSize is not big enough then the negative number
35       of required bytes is returned otherwise the function returns the number
36       of configs and buffer is filled as follows: The first 'numAttribs'
37       integer values are filled with the EGL enumerant describing a config
38       attribute, next for each config there are 'numAttribs' integer values
39       holding the attribute values for that config, the values are specified
40       in the same order as the attribute vector.
41
42EGLint rcChooseConfig(EGLint *attribs, uint32_t attribs_size, uint32_t *configs, uint32_t configs_size)
43       This function triggers an eglChooseConfig on the host, to get a list of
44       configs matching the given attribs values.
45 	attribs - a list of attribute names followed by the desired values, terminated by EGL_NONE
46	attribs_size - the size of the list
47	configs - the returned matching configuration names (same names as familiar to the client in rcGetConfigs)
48	configs_size - the size of the configs buffers
49	returns - the actual number of matching configurations (<= configs_size)
50
51EGLint rcGetFBParam(EGLint param);
52       queries the host for framebuffer parameter, see renderControl_types.h
53       for possible values of 'param'.
54
55uint32_t rcCreateContext(uint32_t config, uint32_t share, uint32_t glVersion);
56       This function creates a rendering context on the host and returns its
57       handle. config is the config index for the context, share is either zero
58       or a handle to a sharing context. glVersion is either 1 or 2 for GLES1
59       or GLES2 context respectively.
60
61
62void rcDestroyContext(uint32_t context);
63       This function destroys a rendering context on the host.
64       context is a handle returned in rcCreateContext.
65
66uint32_t rcCreateWindowSurface(uint32_t config, uint32_t width, uint32_t height);
67       This function creates a 'window' surface on the host which can be then
68       bind for rendering through rcMakeCurrent.
69       The function returns a handle to the created window surface.
70
71void rcDestroyWindowSurface(uint32_t windowSurface);
72       This function destoys a window surface.
73
74uint32_t rcCreateColorBuffer(uint32_t width, uint32_t height, GLenum internalFormat);
75       This function creates a colorBuffer object on the host which can be then
76       be specified as a render target for a window surface through
77       rcSetWindowColorBuffer or to be displayed on the framebuffer window
78       through rcFBPost.
79       The function returns a handle to the colorBuffer object, with an initial
80       reference count of 1.
81
82void rcOpenColorBuffer(uint32_t colorbuffer);
83       Adds an additional reference to the colorbuffer, typically from a
84       different Android process than the one which created it.
85
86void rcCloseColorBuffer(uint32_t colorbuffer);
87       Removes a reference to the colorbuffer. When the reference count drops
88       to zero the colorbuffer is automatically destroyed.
89
90void rcFlushWindowColorBuffer(uint32_t windowSurface, uint32_t colorBuffer);
91       This flushes the current window color buffer
92
93void rcSetWindowColorBuffer(uint32_t windowSurface, uint32_t colorBuffer);
94       This set the target color buffer for a windowSurface, when set the
95       previous target colorBuffer gets updated before switching to the new
96       colorBuffer.
97
98EGLint rcMakeCurrent(uint32_t context, uint32_t drawSurf, uint32_t readSurf);
99       Binds a windowSurface(s) and current rendering context for the
100       calling thread.
101
102void rcFBPost(uint32_t colorBuffer);
103       This function causes the content of the colorBuffer object to be
104       displayed on the host framebuffer window. The function returns
105       immediatly, the buffer will be displayed at the next swap interval.
106
107void rcFBSetSwapInterval(EGLint interval);
108       Sets the swap interval for the host framebuffer window.
109
110void rcBindTexture(uint32_t colorBuffer);
111       This function instruct the host to bind the content of the specified
112       colorBuffer to the current binded texture object of the calling thread.
113       This function should be used to implement eglBindTexImage.
114
115EGLint rcColorBufferCacheFlush(uint32_t colorbuffer, EGLint postCount, int forRead);
116       This function returns only after all rendering requests for the specified
117       colorBuffer rendering target has been processed and after all 'postCount'
118       posts for the buffer requested previously through rcFBPost has been
119       processed.
120       if 'forRead' is not-zero, the function returns positive value in case
121       there was rendering done to the buffer since the last CacheFlush request
122       with non-zero 'forRead' value, otherwise the function returns zero or
123       negative value on failure.
124
125void rcReadColorBuffer(uint32_t colorbuffer, GLint x, GLint y,
126                       GLint width, GLint height, GLenum format,
127                       GLenum type, void* pixels);
128       This function queries the host for the pixel content of a colorBuffer's
129       subregion. It act the same as OpenGL glReadPixels however pixels
130       are always packed with alignment of 1.
131
132void rcUpdateColorBuffer(uint32_t colorbuffer, GLint x, GLint y,
133                         GLint width, GLint height, GLenum format,
134                         GLenum type, void* pixels);
135       Updates the content of a subregion of a colorBuffer object.
136       pixels are always unpacked with alignment of 1.
137
138uint32_t rcCreateClientImage(uint32_t context, EGLenum target, GLuint buffer)
139       Create an EGLImage from a client object.
140
141int rcDestroyClientImage(uint32_t image)
142       Destroy an EGLImage object.
143