~~NOTOC~~

====== clCreateBuffer ======

Legt einen Buffer / ein Speicherobjekt für Daten auf dem OpenCL-Device an.

===== Signatur =====

<code c>
cl_mem clCreateBuffer ( cl_context context,
                        cl_mem_flags flags,
                        size_t size,
                        void *host_ptr,
                        cl_int *errcode_ret)
</code>

====== Parameter ======

**context:** Der gültige OpenCL-Kontext, der für das Erzeugen des Buffer-Objektes benutzt werden soll.

**flags:** Bitfeld, was Informationen über Allokation und Nutzung angibt, wie zum Beispiel wo der Speicher belegt werden soll und wie er benutzt werden soll. Folgende Tabelle gibt mögliche Werte an, ist 0 übergeben, dann wird der Standardwert (CL_MEM_READ_WRITE) benutzt. 

^ cl_mem_flags ^ Beschreibung ^
| CL_MEM_READ_WRITE | Standardwert. Das Speicherobjekt wird gelesen und geschrieben. CL_MEM_WRITE_ONLY und CL_MEM_READ_ONLY und CL_MEM_READ_WRITE schließen sich gegenseitig aus. |
| CL_MEM_WRITE_ONLY | Wird beschrieben, aber nie vom Kernel gelesen. Eine Leseoperation auf einen solchen Puffer ist nicht definiert. CL_MEM_WRITE_ONLY und CL_MEM_READ_ONLY und CL_MEM_READ_WRITE schließen sich gegenseitig aus. |
| CL_MEM_READ_ONLY | Das Speicherobjekt soll nur gelesen werden. Schreiboperationen auf einen solchen Puffer sind nicht defininert. CL_MEM_WRITE_ONLY und CL_MEM_READ_ONLY und CL_MEM_READ_WRITE schließen sich gegenseitig aus. |
| CL_MEM_USE_HOST_PTR | Dieses Flag ist nur dann gültig, wenn der Parameter //host_ptr// nicht NULL ist. Der Speicherbereich, auf den //host_ptr// verweist soll für die Speicherung der Daten benutzt werden. OpenCL kann den Speicherbereich auf dem Gerät cachen. Dieser Cache kann später vom Kernel benutzt werden. Das Verhalten, wenn mehrere OpenCL Kommandos auf verschiedenen Bufferobjekten mit demselben //host_ptr// durchgeführt werden, ist nicht definiert. Siehe [[http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/dataTypes.html|[3]]]. |
| CL_MEM_ALLOC_HOST_PTR | gibt an, dass die Applikation will, dass die OpenCL Implementation Speicher alloziiert, der vom Host aus zugreifbar ist. CL_MEM_ALLOC_HOST_PTR und CL_MEM_USE_HOST_PTR schließen sich gegenseitig aus. |
| CL_MEM_COPY_HOST_PTR | //host_ptr// darf nicht NULL sein. OpenCL soll Speicher für das Speicherobjekt alloziieren und die Daten, auf die //host_ptr// verweist kopieren. CL_MEM_COPY_HOST_PTR und CL_MEM_USE_HOST_PTR schließen sich gegenseitig aus. |
| CL_MEM_HOST_WRITE_ONLY | gibt an, dass der Host auf das Speicherobjekt nur schreiben will (unter Benutzung der OpenCL APIs). Das kann benutzt werden um Schreibzugriffe vom Host zu optimieren (zum Beispiel indem das Alloziieren mit einem Schreibvorgang kombiniert wird für Geräte die über einen System Bus kommunizieren z.B. PCIe). CL_MEM_HOST_WRITE_ONLY und CL_MEM_HOST_READ_ONLY und CL_MEM_HOST_NO_ACCESS schließen sich gegenseitig aus. |
| CL_MEM_HOST_READ_ONLY | gibt an, dass der Host auf das Speicherobjekt nur lesen will (mithilfe der OpenCL API). CL_MEM_HOST_WRITE_ONLY und CL_MEM_HOST_READ_ONLY und CL_MEM_HOST_NO_ACCESS schließen sich gegenseitig aus. |
| CL_MEM_HOST_NO_ACCESS | gibt an, dass der Host weder lesen noch schreiben will. CL_MEM_HOST_WRITE_ONLY und CL_MEM_HOST_READ_ONLY und CL_MEM_HOST_NO_ACCESS schließen sich gegenseitig aus. |

**size:** gibt die Größe in Bytes an, die für das Speicherobjekt reserviert werden sollen.

**host_ptr:** Ein Zeiger auf die Buffer-Daten, die bereits von der Host-Applikation bereits angelegt wurden. Die Größe des Speicherbereiches, auf welches //host_pointer// zeigt, muss wenigstens so groß sein wie //size//.

**errcode_ret:** Gibt einen entsprechenden Fehlercode zurück. Wenn //errcode_ret// NULL ist, wird kein Fehlercode zurückgegeben. Mögliche Fehlercodes:

^ Wert ^ Beschreibung ^
| CL_SUCCESS | Das Buffer-Objekt wurde erfolgreich erstellt und ein Buffer-Objekt, was ungleich 0 ist wurde zurückgegeben. |
| CL_INVALID_CONTEXT | Der übergebene OpenCL-Kontext ist ungültig |
| CL_INVALID_VALUE | der Parameter //flags// enthält ungültige Werte |
| CL_INVALID_BUFFER_SIZE | //size// ist 0. Außerdem kann die OpenCL-Implementation diesen Fehlercode zurückliefern, wenn //size// größer ist als CL_DEVICE_MAX_MEM_ALLOC_SIZE, was mithilfe von //clGetDeviceInfo// abgefragt werden kann. (siehe [[http://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/clGetDeviceInfo.html|[4]]]). |
| CL_INVALID_HOST_PTR | wenn der //host_ptr// NULL ist und CL_MEM_USE_HOST_PTR oder CL_MEM_COPY_HOST_PTR sind in //flags// gesetzt oder wenn der //host_ptr// nicht NULL ist und CL_MEM_COPY_HOST_PTR oder CL_MEM_USE_HOST_PTR sind nicht in den //flags// gesetzt. |
| CL_MEM_OBJECT_ALLOCATION_FAILURE | Ein Fehler bei der Reservierung des Speicherobjekts aufgetreten |
| 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. |

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

Identifier für das Speicherobjekt.

===== Beispiel =====

<code c>
#define LIST_SIZE 12

// context=clCreateContext(...)

int ret=0;

cl_mem a_mem_obj = clCreateBuffer(context, CL_MEM_READ_ONLY, LIST_SIZE * sizeof(int), NULL, &ret);
cl_mem b_mem_obj = clCreateBuffer(context, CL_MEM_READ_ONLY, LIST_SIZE * sizeof(int), NULL, &ret);
cl_mem c_mem_obj = clCreateBuffer(context, CL_MEM_WRITE_ONLY, LIST_SIZE * sizeof(int), NULL, &ret);
</code>