~~NOTOC~~

====== clEnqueueWriteBuffer ======


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

===== Signatur =====
  
<code c>
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)
</code>

===== Parameter =====

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

===== Hinweise =====

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.

===== Rückgabewert =====

Zurückgegeben wird einer der Fehlercodes:

^ Wert ^ Beschreibung ^ 
| CL_SUCCESS | Der Schreibbefehl wurde erfolgreich in die Command Queue eingefügt. |
| CL_INVALID_COMMAND_QUEUE | //command_queue// ist keine gültige Command Queue |
| CL_INVALID_CONTEXT | //command_queue// und //buffer// oder //command_queue// und die Events in //event_wait_list// wurden nicht im gleichen Kontext erzeugt. |
| CL_INVALID_MEM_OBJECT | //buffer// ist kein gültiges Buffer-Objekt |
| CL_NVALID_VALUE | Der Speicherbereich, der durch (//offset//, //size//) gegeben ist, befindet sich außerhalb der Speichergrenzen oder //ptr// ist NULL oder //size// ist 0 |
| CL_INVALID_EVENT_WAIT_LIST | //event_wait_list// ist NULL und //num_events_in_wait_list// ist größer als 0 oder //event_wait_list// ist nicht NULL aber //num_events_in_wait_list// ist 0 oder wenn Event-Objekte in //event_wait_list// keine gültigen Objekte sind. |
| CL_MISALIGNED_SUB_BUFFER_OFFSET | //buffer// ist ein Sub-Buffer-Objekt und //offset//, der benutzt wurde um das Sub-Buffer-Objekt zu erzeugen, wurde nicht an CL_DEVICE_MEM_BASE_ADDR_ALIGN des Gerätes ausgerichtet |
| CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST | Wenn die Lese- und Schreiboperationen blockieren und der Ausführungsstatus von einem Event in der //event_wait_list// ist ein negativer Integer-Wert |
| CL_MEM_OBJECT_ALLOCATION_FAILURE | Es ist ein Fehler beim Reservieren des Speichers für das Datenspeichern aufgetreten. |
| CL_INVALID_OPERATION | //clEnqueueWriteBuffer// wird auf einen //buffer// angewendet, der mit CL_MEM_HOST_READ_ONLY oder CL_MEM_HOST_NO_ACCESS erzeugt wurde |
| CL_OUT_OF_RESOURCES | Es ist ein Fehler beim Reservieren von Speicher aufgetreten, der für die OpenCL-Implementation auf dem Gerät gebraucht wird. |
| CL_OUT_OF_HOST_MEMORY | Es ist ein Fehler beim Reservieren von Speicher aufgetreten, der für die OpenCL-Implementation auf dem Hostprozressor gebraucht wird. |

===== Beispiel =====

<code c>
#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);</code>

===== Siehe auch =====

  * [[opencl:reference:clcreatebuffer|clCreateBuffer]]
  * [[opencl:reference:clcreatecommandqueue|clCreateCommandQueue]]