Sie befinden sich hier: Willkommen bei proggen.org! » OpenCL » reference » clCreateBuffer

Seitenleiste

Community

Tutorials

Einstieg

Nativ

Web-Programmierung

Fachthemen

mehr...

clCreateBuffer

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

Signatur

cl_mem clCreateBuffer ( cl_context context,
                        cl_mem_flags flags,
                        size_t size,
                        void *host_ptr,
                        cl_int *errcode_ret)

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 [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 [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

#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);