clCreateProgramWithSource

Creates a program object for a context, and loads the source code specified by the text strings in the strings array into the program object.

`cl_program clCreateProgramWithSource (`	cl_context `context`,
	cl_uint `count`,
	const char `**strings`,
	const size_t `*lengths`,
	cl_int `*errcode_ret)`

Parameters

context: Must be a valid OpenCL context.
strings: An array of count pointers to optionally null-terminated character strings that make up the source code.
lengths: An array with the number of chars in each string (the string length). If an element in lengths is zero, its accompanying string is null-terminated. If lengths is NULL, all strings in the strings argument are considered null-terminated. Any length value passed in that is greater than zero excludes the null terminator in its count.
errcode_ret: Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

Notes

The devices associated with the program object are the devices associated with context.

OpenCL allows applications to create a program object using the program source or binary and build appropriate program executables. This allows applications to determine whether they want to use the pre-built offline binary or load and compile the program source and use the executable compiled/linked online as the program executable. This can be very useful as it allows applications to load and build program executables online on its first instance for appropriate OpenCL devices in the system. These executables can now be queried and cached by the application. Future instances of the application launching will no longer need to compile and build the program executables. The cached executables can be read and loaded by the application, which can help significantly reduce the application initialization time.

An OpenCL program consists of a set of kernels that are identified as functions declared with the __kernel qualifier in the program source. OpenCL programs may also contain auxiliary functions and constant data that can be used by __kernel functions. The program executable can be generated online or offline by the OpenCL compiler for the appropriate target device(s).

Errors

clCreateProgramWithSource returns a valid non-zero program object and errcode_ret is set to CL_SUCCESS if the program object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

CL_INVALID_CONTEXT if context is not a valid context.
CL_INVALID_VALUE if count is zero or if strings or any entry in strings is NULL.
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

Specification

OpenCL Specification

Also see

clCreateProgramWithBinary, clReleaseProgram, clRetainProgram, Cardinality Diagram

Copyright © 2007-2010 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.