examples: annotate examples
[nit.git] / lib / glesv2 / glesv2.nit
index 8fe9f9b..c4ac331 100644 (file)
@@ -31,6 +31,7 @@
 # http://www.khronos.org/opengles/sdk/docs/man/
 module glesv2 is
        pkgconfig
+       no_warning "missing-doc"
        new_annotation glsl_vertex_shader
        new_annotation glsl_fragment_shader
        ldflags("-lGLESv2")@android
@@ -81,17 +82,6 @@ extern class GLProgram `{GLuint`}
        # Boolean result of `validate`, must be called after `validate`
        fun is_validated: Bool do return glGetProgramiv(self, gl_VALIDATE_STATUS) != 0
 
-       # Retrieve the information log of this program
-       #
-       # Useful with `link` and `validate`
-       fun info_log: String import NativeString.to_s `{
-               int size;
-               glGetProgramiv(self, GL_INFO_LOG_LENGTH, &size);
-               GLchar *msg = malloc(size);
-               glGetProgramInfoLog(self, size, NULL, msg);
-               return NativeString_to_s(msg);
-       `}
-
        # Number of active uniform in this program
        #
        # This should be the number of uniforms declared in all shader, except
@@ -117,17 +107,18 @@ extern class GLProgram `{GLuint`}
        fun active_attrib_name(index: Int): String
        do
                var max_size = active_attribute_max_length
-               return active_attrib_name_native(index, max_size).to_s
+               var cname = new CString(max_size)
+               active_attrib_name_native(index, max_size, cname)
+               return cname.to_s
        end
-       private fun active_attrib_name_native(index, max_size: Int): NativeString `{
+
+       private fun active_attrib_name_native(index, max_size: Int, name: CString) `{
                // We get more values than we need, for compatibility. At least the
                // NVidia driver tries to fill them even if NULL.
 
-               char *name = malloc(max_size);
                int size;
                GLenum type;
                glGetActiveAttrib(self, index, max_size, NULL, &size, &type, name);
-               return name;
        `}
 
        # Size of the active attribute at `index`
@@ -151,15 +142,16 @@ extern class GLProgram `{GLuint`}
        # Name of the active uniform at `index`
        fun active_uniform_name(index: Int): String
        do
-               var max_size = active_attribute_max_length
-               return active_uniform_name_native(index, max_size).to_s
+               var max_size = active_uniform_max_length
+               var cname = new CString(max_size)
+               active_uniform_name_native(index, max_size, cname)
+               return cname.to_s
        end
-       private fun active_uniform_name_native(index, max_size: Int): NativeString `{
-               char *name = malloc(max_size);
+
+       private fun active_uniform_name_native(index, max_size: Int, name: CString) `{
                int size;
                GLenum type;
                glGetActiveUniform(self, index, max_size, NULL, &size, &type, name);
-               return name;
        `}
 
        # Size of the active uniform at `index`
@@ -196,7 +188,7 @@ fun glValidateProgram(program: GLProgram) `{ glValidateProgram(program); `}
 # Delete the `program` object
 fun glDeleteProgram(program: GLProgram) `{ glDeleteProgram(program); `}
 
-# Determine if `name` corresponds to a program object
+# Does `name` corresponds to a program object?
 fun glIsProgram(name: GLProgram): Bool `{ return glIsProgram(name); `}
 
 # Attach a `shader` to `program`
@@ -212,8 +204,17 @@ fun glGetProgramiv(program: GLProgram, pname: GLGetParameterName): Int `{
        return value;
 `}
 
+# The information log for the `program` object
+fun glGetProgramInfoLog(program: GLProgram): String
+do
+       var size = glGetProgramiv(program, gl_INFO_LOG_LENGTH)
+       var buf = new CString(size)
+       native_glGetProgramInfoLog(program, size, buf)
+       return buf.to_s_with_length(size)
+end
+
 # Return the program information log in `buf`
-fun glGetProgramInfoLog(program: GLProgram, buf_size: Int, buf: NativeString): Int `{
+private fun native_glGetProgramInfoLog(program: GLProgram, buf_size: Int, buf: CString): Int `{
        int length;
        glGetProgramInfoLog(program, buf_size, &length, buf);
        return length;
@@ -233,7 +234,7 @@ extern class GLShader `{GLuint`}
                return source_native(size).to_s
        end
 
-       private fun source_native(size: Int): NativeString `{
+       private fun source_native(size: Int): CString `{
                GLchar *code = malloc(size);
                glGetShaderSource(self, size, NULL, code);
                return code;
@@ -243,17 +244,6 @@ extern class GLShader `{GLuint`}
        fun is_compiled: Bool do return glGetShaderiv(self, gl_COMPILE_STATUS) != 0
 
        # Has this shader been deleted?
-
-       # Retrieve the information log of this shader
-       #
-       # Useful with `link` and `validate`
-       fun info_log: String import NativeString.to_s `{
-               int size;
-               glGetShaderiv(self, GL_INFO_LOG_LENGTH, &size);
-               GLchar *msg = malloc(size);
-               glGetShaderInfoLog(self, size, NULL, msg);
-               return NativeString_to_s(msg);
-       `}
        fun is_deleted: Bool do return glGetShaderiv(self, gl_DELETE_STATUS) != 0
 end
 
@@ -284,6 +274,21 @@ fun gl_ATTACHED_SHADERS: GLGetParameterName `{ return GL_ATTACHED_SHADERS; `}
 fun gl_LINK_STATUS: GLGetParameterName `{ return GL_LINK_STATUS; `}
 fun gl_VALIDATE_STATUS: GLGetParameterName `{ return GL_VALIDATE_STATUS; `}
 
+# The information log for the `shader` object
+fun glGetShaderInfoLog(shader: GLShader): String
+do
+       var size = glGetShaderiv(shader, gl_INFO_LOG_LENGTH)
+       var buf = new CString(size)
+       native_glGetShaderInfoLog(shader, size, buf)
+       return buf.to_s_with_length(size)
+end
+
+private fun native_glGetShaderInfoLog(shader: GLShader, buf_size: Int, buffer: CString): Int `{
+       int length;
+       glGetShaderInfoLog(shader, buf_size, &length, buffer);
+       return length;
+`}
+
 # Shader type
 extern class GLShaderType
        super GLEnum
@@ -298,7 +303,7 @@ fun glCreateShader(shader_type: GLShaderType): GLShader `{
 `}
 
 # Replace the source code in the `shader` object with `code`
-fun glShaderSource(shader: GLShader, code: NativeString) `{
+fun glShaderSource(shader: GLShader, code: CString) `{
        glShaderSource(shader, 1, (GLchar const **)&code, NULL);
 `}
 
@@ -308,7 +313,7 @@ fun glCompileShader(shader: GLShader) `{ glCompileShader(shader); `}
 # Delete the `shader` object
 fun glDeleteShader(shader: GLShader) `{ glDeleteShader(shader); `}
 
-# Determine if `name` corresponds to a shader object
+# Does `name` corresponds to a shader object?
 fun glIsShader(name: GLShader): Bool `{ return glIsShader(name); `}
 
 # An OpenGL ES 2.0 fragment shader
@@ -371,11 +376,26 @@ fun glDisableVertexAttribArray(index: Int) `{ glDisableVertexAttribArray(index);
 # Render primitives from array data
 fun glDrawArrays(mode: GLDrawMode, from, count: Int) `{ glDrawArrays(mode, from, count); `}
 
+# Render primitives from array data by their index listed in `indices`
+fun glDrawElements(mode: GLDrawMode, count: Int, typ: GLDataType, indices: Pointer) `{
+       glDrawElements(mode, count, typ, indices);
+`}
+
+# Render primitives from array data, at `offset` in the element buffer
+fun glDrawElementsi(mode: GLDrawMode, count: Int, typ: GLDataType, offset: Int) `{
+       glDrawElements(mode, count, typ, (const GLvoid*)offset);
+`}
+
 # Define an array of generic vertex attribute data
 fun glVertexAttribPointer(index, size: Int, typ: GLDataType, normalized: Bool, stride: Int, array: NativeGLfloatArray) `{
        glVertexAttribPointer(index, size, typ, normalized, stride, array);
 `}
 
+# Define an array of generic vertex attribute data, at `offset` in the array buffer
+fun glVertexAttribPointeri(index, size: Int, typ: GLDataType, normalized: Bool, stride: Int, offset: Int) `{
+       glVertexAttribPointer(index, size, typ, normalized, stride, (const GLvoid*)offset);
+`}
+
 # Specify the value of a generic vertex attribute
 fun glVertexAttrib1f(index: Int, x: Float) `{ glVertexAttrib1f(index, x); `}
 
@@ -400,7 +420,17 @@ fun glUniform3i(index, x, y, z: Int) `{ glUniform3i(index, x, y, z); `}
 # Specify the value of a uniform variable for the current program object
 fun glUniform4i(index, x, y, z, w: Int) `{ glUniform4i(index, x, y, z, w); `}
 
-# TODO glUniform*f
+# Specify the value of a uniform variable for the current program object
+fun glUniform1f(index: Int, x: Float) `{ glUniform1f(index, x); `}
+
+# Specify the value of a uniform variable for the current program object
+fun glUniform2f(index: Int, x, y: Float) `{ glUniform2f(index, x, y); `}
+
+# Specify the value of a uniform variable for the current program object
+fun glUniform3f(index: Int, x, y, z: Float) `{ glUniform3f(index, x, y, z); `}
+
+# Specify the value of a uniform variable for the current program object
+fun glUniform4f(index: Int, x, y, z, w: Float) `{ glUniform4f(index, x, y, z, w); `}
 
 # Low level array of `Float`
 class GLfloatArray
@@ -421,11 +451,18 @@ class GLfloatArray
        end
 
        # Fill with the content of `array`
-       fun fill_from(array: Array[Float])
+       #
+       # If `dst_offset` is set, the data is copied to the index `dst_offset`,
+       # otherwise, it is copied the beginning of `self`.
+       #
+       # Require: `length >= array.length + dst_offset or else 0`
+       fun fill_from(array: Array[Float], dst_offset: nullable Int)
        do
-               assert length >= array.length
+               dst_offset = dst_offset or else 0
+
+               assert length >= array.length + dst_offset
                for k in [0..array.length[ do
-                       self[k] = array[k]
+                       self[dst_offset+k] = array[k]
                end
        end
 end
@@ -675,7 +712,7 @@ private fun native_glGenRenderbuffers(n: Int, renderbuffers: NativeCIntArray) `{
        glGenRenderbuffers(n, (GLuint *)renderbuffers);
 `}
 
-# Determine if `name` corresponds to a renderbuffer object
+# Does `name` corresponds to a renderbuffer object?
 fun glIsRenderbuffer(name: Int): Bool `{
        return glIsRenderbuffer(name);
 `}
@@ -716,10 +753,10 @@ fun gl_RGBA4: GLRenderbufferFormat `{ return GL_RGBA4; `}
 fun gl_RGB565: GLRenderbufferFormat `{ return GL_RGB565; `}
 
 # 5 red, 5 green, 5 blue, 1 alpha bits format
-fun gl_RGB_A1: GLRenderbufferFormat `{ return GL_RGB5_A1; `}
+fun gl_RGB5_A1: GLRenderbufferFormat `{ return GL_RGB5_A1; `}
 
 # 16 depth bits format
-fun gl_DEPTH_COMPNENT16: GLRenderbufferFormat `{ return GL_DEPTH_COMPONENT16; `}
+fun gl_DEPTH_COMPONENT16: GLRenderbufferFormat `{ return GL_DEPTH_COMPONENT16; `}
 
 # 8 stencil bits format
 fun gl_STENCIL_INDEX8: GLRenderbufferFormat `{ return GL_STENCIL_INDEX8; `}
@@ -857,6 +894,62 @@ fun glHint(target: GLHintTarget, mode: GLHintMode) `{
 # Generate and fill set of mipmaps for the texture object `target`
 fun glGenerateMipmap(target: GLTextureTarget) `{ glGenerateMipmap(target); `}
 
+# Generate `n` buffer names
+fun glGenBuffers(n: Int): Array[Int]
+do
+       var array = new CIntArray(n)
+       native_glGenBuffers(n, array.native_array)
+       var a = array.to_a
+       array.destroy
+       return a
+end
+
+private fun native_glGenBuffers(n: Int, buffers: NativeCIntArray) `{
+       glGenBuffers(n, (GLuint *)buffers);
+`}
+
+# Does `name` corresponds to a buffer object?
+fun glIsBuffer(name: Int): Bool `{
+       return glIsBuffer(name);
+`}
+
+# Delete named buffer objects
+fun glDeleteBuffers(buffers: SequenceRead[Int])
+do
+       var n = buffers.length
+       var array = new CIntArray.from(buffers)
+       native_glDeleteBuffers(n, array.native_array)
+       array.destroy
+end
+
+private fun native_glDeleteBuffers(n: Int, buffers: NativeCIntArray) `{
+       return glDeleteBuffers(n, (const GLuint *)buffers);
+`}
+
+# Create and initialize a buffer object's data store
+fun glBufferData(target: GLArrayBuffer, size: Int, data: Pointer, usage: GLBufferUsage) `{
+       glBufferData(target, size, data, usage);
+`}
+
+# Update a subset of a buffer object's data store
+fun glBufferSubData(target: GLArrayBuffer, offset, size: Int, data: Pointer) `{
+       glBufferSubData(target, offset, size, data);
+`}
+
+# Expected usage of a buffer
+extern class GLBufferUsage
+       super GLEnum
+end
+
+# Data will be modified once and used a few times
+fun gl_STREAM_DRAW: GLBufferUsage `{ return GL_STREAM_DRAW; `}
+
+# Data will be modified once and used many times
+fun gl_STATIC_DRAW: GLBufferUsage `{ return GL_STATIC_DRAW; `}
+
+# Data will be modified repeatedly and used many times
+fun gl_DYNAMIC_DRAW: GLBufferUsage `{ return GL_DYNAMIC_DRAW; `}
+
 # Bind the named `buffer` object
 fun glBindBuffer(target: GLArrayBuffer, buffer: Int) `{ glBindBuffer(target, buffer); `}
 
@@ -948,11 +1041,11 @@ do
        return a
 end
 
-private fun native_glGenFramebuffers(n: Int, textures: NativeCIntArray) `{
-       glGenFramebuffers(n, (GLuint *)textures);
+private fun native_glGenFramebuffers(n: Int, framebuffers: NativeCIntArray) `{
+       glGenFramebuffers(n, (GLuint *)framebuffers);
 `}
 
-# Determine if `name` corresponds to a framebuffer object
+# Does `name` corresponds to a framebuffer object?
 fun glIsFramebuffer(name: Int): Bool `{
        return glIsFramebuffer(name);
 `}
@@ -1114,6 +1207,7 @@ end
 fun gl_ALPHA: GLPixelFormat `{ return GL_ALPHA; `}
 fun gl_RGB: GLPixelFormat `{ return GL_RGB; `}
 fun gl_RGBA: GLPixelFormat `{ return GL_RGBA; `}
+fun gl_DEPTH_COMPONENT: GLPixelFormat `{ return GL_DEPTH_COMPONENT; `}
 
 # Set of buffers as a bitwise OR mask
 extern class GLBuffer `{ GLbitfield `}
@@ -1175,3 +1269,63 @@ fun glPolygonOffset(factor, units: Float) `{ glPolygonOffset(factor, units); `}
 
 # Specify the width of rasterized lines
 fun glLineWidth(width: Float) `{ glLineWidth(width); `}
+
+# Get the value of the parameter `pname` at `offset`
+fun glGetBooleanv(pname: GLGetParameterName, offset: Int): Bool `{
+       GLboolean v[4];
+       glGetBooleanv(pname, v);
+       return v[offset];
+`}
+
+# Get the value of the parameter `pname` at `offset`
+fun glGetFloatv(pname: GLGetParameterName, offset: Int): Float `{
+       GLfloat v[4];
+       glGetFloatv(pname, v);
+       return v[offset];
+`}
+
+# Get the value of the parameter `pname` at `offset`
+fun glGetIntegerv(pname: GLGetParameterName, offset: Int): Int `{
+       GLint v[4];
+       glGetIntegerv(pname, v);
+       return v[offset];
+`}
+
+fun gl_COLOR_CLEAR_VALUE: GLGetParameterName `{ return GL_COLOR_CLEAR_VALUE; `}
+
+fun gl_MAX_TEXTURE_SIZE: GLGetParameterName `{ return GL_MAX_TEXTURE_SIZE; `}
+fun gl_MAX_VIEWPORT_DIMS: GLGetParameterName `{ return GL_MAX_VIEWPORT_DIMS; `}
+fun gl_MAX_VERTEX_ATTRIBS: GLGetParameterName `{ return GL_MAX_VERTEX_ATTRIBS; `}
+fun gl_MAX_VERTEX_UNIFORM_VECTORS: GLGetParameterName `{ return GL_MAX_VERTEX_UNIFORM_VECTORS; `}
+fun gl_MAX_VARYING_VECTORS: GLGetParameterName `{ return GL_MAX_VARYING_VECTORS; `}
+fun gl_MAX_COMBINED_TEXTURE_IMAGE_UNITS: GLGetParameterName `{ return GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS; `}
+fun gl_MAX_VERTEX_TEXTURE_IMAGE_UNITS: GLGetParameterName `{ return GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS; `}
+fun gl_MAX_TEXTURE_IMAGE_UNITS: GLGetParameterName `{ return GL_MAX_TEXTURE_IMAGE_UNITS; `}
+fun gl_MAX_FRAGMENT_UNIFORM_VECTORS: GLGetParameterName `{ return GL_MAX_FRAGMENT_UNIFORM_VECTORS; `}
+
+fun gl_ARRAY_BUFFER_BINDING: GLGetParameterName `{ return GL_ARRAY_BUFFER_BINDING; `}
+fun gl_ELEMENT_ARRAY_BUFFER_BINDING: GLGetParameterName `{ return GL_ELEMENT_ARRAY_BUFFER_BINDING; `}
+fun gl_TEXTURE_BINDING_2D: GLGetParameterName `{ return GL_TEXTURE_BINDING_2D; `}
+fun gl_TEXTURE_BINDING_CUBE_MAP: GLGetParameterName `{ return GL_TEXTURE_BINDING_CUBE_MAP; `}
+fun gl_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING: GLGetParameterName `{ return GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING; `}
+fun gl_FRAMEBUFFER_BINDING: GLGetParameterName `{ return GL_FRAMEBUFFER_BINDING; `}
+fun gl_RENDERBUFFER_BINDING: GLGetParameterName `{ return GL_RENDERBUFFER_BINDING; `}
+
+# Return a string describing the current GL configuration
+fun glGetString(name: GLEnum): String do return glGetString_native(name).to_s
+private fun glGetString_native(name: GLEnum): CString `{ return (char*)glGetString(name); `}
+
+# Company responsible for this GL implementation
+fun gl_VENDOR: GLEnum `{ return GL_VENDOR; `}
+
+# Name of the renderer, typically specific to a particular configuration of the hardware platform
+fun gl_RENDERER: GLEnum `{ return GL_RENDERER; `}
+
+# Version or release number
+fun gl_VERSION: GLEnum `{ return GL_VERSION; `}
+
+# Version or release number for the shading language of the form
+fun gl_SHADING_LANGUAGE_VERSION: GLEnum `{ return GL_SHADING_LANGUAGE_VERSION; `}
+
+# Space-separated list of supported extensions to GL
+fun gl_EXTENSIONS: GLEnum `{ return GL_EXTENSIONS; `}