Fügt ein Kommando zum Schreiben auf ein Buffer-Objekt vom Host-Speicher in die Command Queue ein.

cl_int clEnqueueWriteBuffer ( cl_command_queue command_queue,
                              cl_mem buffer,
                              cl_bool blocking_write,
                              size_t offset,
                              size_t size,
                              const void *ptr,
                              cl_uint num_events_in_wait_list,
                              const cl_event *event_wait_list,
                              cl_event *event)

command_queue: eine gültige Host-Command-Queue in die der Schreibbefehl eingefügt werden soll. command_queue und buffer müssen im selben OpenCL-Kontext erzeugt worden sein.

buffer: Referenziert ein gültiges Buffer-Objekt.

blocking_wirte: zeigt an, ob die Schreiboperation blockieren oder nicht blockieren soll. Falls auf CL_TRUE gestellt: die OpenCL-Implementation kopiert die Daten, auf die von ptr gezeigt wird und fügt die Schreiboperation in die CommandQueue. Der Speicher, auf den ptr zeigt kann nachdem clEnqueueWriteBuffer zurückgekehrt ist wieder benutzt werden. CL_FALSE: Die Implementation wird sofort zurückkehren, der Speicherbereich kann nicht sofort wiederverwendet werden. event gibt einen Identifier zurück, mithilfe dessen auf die Beendigung des Schreibbefehls gewartet werden kann, erst danach kann der Speicher wieder benutzt werden.

offset: Der Offset in Bytes (also indirekte Adressierung) wohin ins Buffer-Objekt geschrieben wird.

size: Die Größe der Daten, die geschrieben werden soll in Bytes.

ptr: Pointer auf den Speicherblock im Host-Speicher von dem die Daten geschrieben werden sollen.

event_wait_list, num_events_in_wait_list: geben eine Liste der Kommandos an, die fertig gestellt sein müssen, bevor der Schreibbefehl ausgeführt wird. Wenn event_wait_list NULL ist, dann wird auf nichts gewartet. num_events_in_wait_list muss dann ebenfalls 0 sein. Die Events, die in der Warteliste angegeben sind, agieren als eine Art Synchronisationspunkt. Der OpenCL-Kontext der Events in der Warteliste und die Command Queue müssen die selben sein. Der Speicher von event_wait_list kann nach dem die Funktion zurückgekehrt ist wieder benutzt werden.

event: gibt ein Event zurück, was diese Schreiboperation eindeutig identifiziert. Dieser Wert kann benutzt werden um den Befehl abzufragen oder einen Wartebefehl für diesen Befehl in die Command Queue einzufügen. event kann NULL sein, dann ist es nicht möglich den Status des Befehls abzufragen oder auf den Befehl zu warten. Wenn event und event_wait_list nicht NULL sind, dann sollte event nicht auf ein Element in der event_wait_list zeigen.

Wenn clEnqueueWriteBuffer dazu eingesetzt wird, die neusten Bits eines Teils des Puffers zu aktualisieren (mit ptr=host_ptr + offset; host_ptr ist dabei der Zeiger auf die Speicherregion, die benutzt wurde als das Bufferobjekt mit CL_MEM_USE_HOST_PTR erzeugt wurde) dann müssen folgende Voraussetzungen erfüllt sein, damit kein undefiniertes Verhalten auftritt:

• Der Speicherbereich des Hosts, der durch (host_ptr + offset, size) gegeben wurde enthält die neusten Bits, wenn das eingereihte Schreibkommando startet
• Das Bufferobjekt oder Speicherobjekt, was von diesem Speicherbereich erzeugt wurde, ist nicht gemappt
• Das Bufferobjekt oder Speicherobjekt, was von diesem Speicherbereich erzeugt wurde, wird nicht von irgendeiner Command Queue benutzt bis das Lese-Kommando vollständig ausgeführt wurde.

Zurückgegeben wird einer der Fehlercodes:

#define LIST_SIZE 12
 
// command_queue = clCreateCommandQueue (...)
 
// a_mem_obj = clCreateBuffer(...)
 
int *A=(int*) malloc(LIST_SIZE*sizeof(int));
 
for (int i=0; i<LIST_SIZE; i++)
    A[i]=i;
 
ret = clEnqueueWriteBuffer(command_queue, a_mem_obj, CL_TRUE, 0, LIST_SIZE * sizeof(int), A, 0, NULL, NULL);

• clCreateBuffer
• clCreateCommandQueue