[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Public WebGL] WebGL Reference Pages






On Tue, Aug 14, 2012 at 11:10 AM, Mark Callow <callow_mark@hicorp.co.jp> wrote:
On 12/08/13 19:15, Benoit Jacob wrote:
On the one hand, we have markup language that make it easy to write documents. On the other hand we have XML which gives automation but is a pain to write by hand. The only document writing system that combines convenient markup with good large-document-structuration-and-automation features, that I know of, is LaTeX. From the looks of the OpenGL [ES] PDF spec, it seems that it's made in LaTeX, for example (maybe someone can confirm). But compared to a wiki, this will increase the barrier to entry quite a bit.
I don't think enabling trivial modifications at the expense of creating an immense amount of manual labor is the right trade-off.

The point of the pages is as information, not automation. Sure automation might save some work but as has been demonstrated with not only the OpenGL and OpenGL ES man pages but also with just about every other project that has docs in a repo vs a wiki, making it easier to edit leads to more and better info.
 

The OpenGL {,ES} specifications are done in LaTeX.

The man pages are done in docbook and writing or editing those is no harder than html. The entry barrier comes in previewing the result as you need various docbook tools and available Unix-like make and scripting to generate the xhtml output. But we could probably run a post-commit script that rebuilds the man pages either on github or khronos.org.

It should also be possible to get the xml source to display directly in some (most) browsers. Currently the files do not reference the necessary xsl files though. Then we just need a server that allows the pages to be edited.

"The Docbook XML source for the OpenGL man pages is available for anonymous checkout in Khronos' Subversion server, and you can build a man page distribution of your own using open source tools. See the OpenGL.org technical Wiki pages describing the XML Toolchain and Man Pages for more information. " says the intro page of the man pages on opengl.org.

The URL is
https://cvs.khronos.org/svn/repos/ogl/trunk/ecosystem/public/sdk/docs
If you look in e.g., man4 for example, you can see the source xml files. The output files are in, e.g., man4/xhtml.

I expect we can persuade Khronos to make the OpenGL ES man page sources similarly available possibly even on github.



On 12/08/14 10:16, Chris Marrin wrote:


Currently, the IDL file is extracted from the spec (see https://github.com/KhronosGroup/WebGL/blob/master/specs/latest/extract-idl.py). Seems like the text for man pages could be similarly extracted. This might involve tagging additional elements in the spec, or adding some hidden elements with additional data. Then maybe the simplest thing to do would be to add this text to the IDL in Doxygen format so we can use those tools to generate various formats of man pages?


If it wasn't for the issue that a lot of information will be duplicated between this and the OpenGL ES man pages and the related issue that the WebGL spec is not a complete standalone specification, I'd say go for it. 

I don't believe sharing info with the OpenGL ES man pages is really going to be all that useful. OpenGL ES is a C library. WebGL is a _javascript_ library. OpenGL ES has a different API. Some places take GLint or GLuint where WebGL takes objects glBindTexture(target, texture_id) vs bindTexture(target, WebGLTexture). Some functions have been changed, glGetIntegerv, glGetFloatv, glGetBooeanv -> getParameter. glGenTextures -> createTexture. Function names are different glUniform1fv  vs uniform1fv.  Some functions have different parameters. glTexImage2D(target, level, internal_format, width, height, border, format, type, data) vs texImage2D(target, level, internal_format, format, type, element). On top of that WebGL can be execute in the docs, OpenGL can't. WebGL comes with a large library of functions (HTML5) that makes examples easier to write vs C where except for stl and file i/o not much is standardized. In other words,

--how to load a jpg in WebGL--

var img = new Image();
img. {
   loadTexture(img);
}(img);
img.src = "" href="http://somesite.com/someimage.jpg">http://somesite.com/someimage.jpg";

function loadTexture(img) {
  var texture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, myTexture);
  gl.texImage2D(gl.TEXURE_2D, 0, gl.RGB, gl.RGB, gl.UNSIGNED_BYTE, img);
}

--How to load a jpg in OpenGL--

// Load jpg file.
j = loadJPGSomeFunctionLeftAsAnExerciseForTeReader(jpg);

int width = getWidthSomeFunctionLeftAsAnExerciseForTheReader(jpg)
int height = getHeightSomeFunctionLeftAsAnExerciseForTheReader(jpg);
const void* data = "">

glBindTexture(GL_TEXTURE_2D, my_texture_id);
glTexImage2D(GL_TEXURE_2D, 0, GL_RGB, width, height, 0, gl.RGB, UNSIGNED_BYTE, data);

// need to free the image.
freeJPGSomeFunctionLeftAsAnExerciseForTheReader(jpg);

The WebGL code works. The OpenGL code is psuedo code.

It seems like trying to share info will only make things more confusing and difficult.
 

Regards

-Mark

--
注意:この電子メールには、株式会社エイチアイの機密情報が含まれている場合が有ります。正式なメール受信者では無い場合はメール複製、 再配信または情報の使用を固く禁じております。エラー、手違いでこのメールを受け取られましたら削除を行い配信者にご連絡をお願いいたし ます。

NOTE: This electronic mail message may contain confidential and privileged information from HI Corporation. If you are not the intended recipient, any disclosure, photocopying, distribution or use of the contents of the received information is prohibited. If you have received this e-mail in error, please notify the sender immediately and permanently delete this message and all related copies.