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_DEBUG

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

2. 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
   

3. 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.

4. 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( cl_uint channeltype*, cl_uint size ) 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. You can use the MACRO CL_SET_TYPE_POINTER(...) who automatically call clSetTypePointer with the good size.

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

5. 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.

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