Tutorial

For build your sample you simply need to use emcc for build you C/C++ sources. You can take a look to the Makefile inside the webcl samples folder.

The WebCL-translator add some build settings for have more info during the execution of the OpenCL/WebCL code.

Settings

1. OPENCL_OLD_VERSION

   Enable the first version of WebCL-translator, this version it's compatible for Firefox and Webkit. It's not compatible with cl.hpp headers, doesn't implement all the OpenCL function. The CL/GL interoperability it's partially supported.

   By default the settings is disabled, and use the last version of WebCL-translator, only compatible with WebKit. With an implementation of all OpenCL function, support of cl.hpp header.

2. OPENCL_DEBUG

   Print message inside the console browser, for more info. It's no so verbose, because some other settings option give more info.

3. OPENCL_GRAB_TRACE

   This is one part of the webcl stack tracer. When you enable it, all the webcl function are grab. This option give access to new function webclPrintStackTrace(const char*, uint*). When you call it you can have the size of the stack tracer string and the stack tracer string.

    #ifdef __EMSCRIPTEN__
    void print_stack() {
        printf("\n___________________________________\n");
        cl_uint size = 0;
        webclPrintStackTrace(NULL,&size);
   
        char* webcl_stack = (char*)malloc(size+1);
        webcl_stack[size] = '\0';
   
        webclPrintStackTrace(webcl_stack,&size);
        printf("%s\n",webcl_stack);
   
        printf("___________________________________\n");
        free(webcl_stack);
    }
    #endif
   

4. OPENCL_PRINT_TRACE

   This is second part of the webcl stack tracer. Some OpenCL sample can exit without call the same last function, and it's hard to call the webclPrintStackTrace in the good place. This settings it's like a flush of stack tracer. If it's enabled, after each call of OpenCL function. The stack tracer are print inside the console. When you use OPENCL_PRINT_TRACE is not necessary to call webclPrintStackTrace.

5. OPENCL_PROFILE

   For profile your sample you can enable the console profile of the browser. When it's enabled you have access to two function webclBeginProfile(const char *) and webclEndProfile(). The first function enable the console profile and start the timer. The second stop the profile, the timer and print the time elapsed, and the state of the hashmap of webcl object. Currently, you can enclose a part of your code between this two function for profile it.

6. OPENCL_CHECK_SET_POINTER

   Some OpenCL function take void* parameter, with the translator, some info are loose about the type of pointer parameter. For respect the type you need to call clSetTypePointer( channeltype ) before each call of OpenCL function who take a void* parameter. By default the type are Float but the translator support CL_SIGNED_INT8, CL_SIGNED_INT16, CL_SIGNED_INT32, CL_UNSIGNED_INT8, CL_UNSIGNED_INT16, CL_UNSIGNED_INT32, CL_FLOAT. This option print a message inside the console if you call a function who take a pointer without call clSetTypePointer before.

    clSetTypePointer(CL_FLOAT);                               
    err = clEnqueueReadBuffer( commands, output, CL_TRUE, 0, sizeof(float) * count, results, 0, NULL, NULL );  
   

7. OPENCL_CHECK_VALID_OBJECT

   The webcl-translator use an hash map of WebCLObject, for debug, you can enable this settings, in each acces to a WebCLObject inside the hash map, there is a check before if the object is inside or not, and print an error message if necessary.

8. OPENCL_FORCE_CPU

   Some sample can be not compatible with CPU, currently you have an error when you call clEnqueueNDRange. When you enable the settings, you change the behavior of clEnqueueNDRange, and sometime can give a result. Be careful this option it's just for testing and can give crash of your browser

How read Stack Tracer

    clGetDeviceIDs(0,2,1,5048,0)
        ->[object WebCL].getPlatforms()
        ->[object WebCLPlatform].getDevices(2)
	        =>Result (0 : 505347 - 0) - Message () - Exception ()

• First line is the OpenCL C++ call with all the parameter

  • Param 1 -> 0 is the cl_platform_id (NULL in this exemple)
  • Param 2 -> 2 is the cl_device_type (OPENCL_CPU_DEVICE)
  • Param 3 -> 1 is the cl_uint num_entries (Here we want only 1 device)
  • Param 4 -> 5048 is the cl_device_id * (pointer to the devices)
  • Param 5 -> 0 is the cl_uint * (pointer to the num devices)

• Second & Third lines (lines with simple arrow) are the WebCL JS call with all the parameter

  • Line 1 -> The function call getPlatforms because we don't specify platform in this case
  • Line 2 -> The function call getDevices with the device type in parameter

• Last line is the result of the function with the reference parameter

  • Result : before the : we have the return of the function here is return CL_SUCCESS (0), and after the reference parameter, in this case we have two references, first is the cl_device_id (505347 is the UDID of the WebCLObject), second is the num_device (0 because the parameter was NULL);
  • Message : Custom error write by the translator
  • Exception : Error call by the WebCL JS call