JOCL v2.6.0-rc-20250722
JOCL, OpenCL® API Binding for Java™ (public API).
CLMemory.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.opencl;
30
31import com.jogamp.common.nio.Buffers;
32import com.jogamp.common.nio.PointerBuffer;
33import com.jogamp.opencl.llb.CL;
34import com.jogamp.opencl.llb.impl.CLMemObjectDestructorCallback;
35import java.nio.Buffer;
36import java.nio.IntBuffer;
37import java.util.ArrayList;
38import java.util.EnumSet;
39import java.util.List;
40
41import static com.jogamp.opencl.CLException.*;
42import static com.jogamp.opencl.llb.CL.*;
43
44/**
45 * Common superclass for all OpenCL memory types.
46 * Represents an OpenCL memory object and wraps an optional NIO buffer.
47 * @author Michael Bien, et al.
48 */
49public abstract class CLMemory <B extends Buffer> extends CLObjectResource {
50
51 B buffer;
52 protected final int FLAGS;
53 protected long size;
54
55 // depends on the nio buffer type
56 protected int elementSize;
57 protected int clCapacity;
58
59 private final CL binding;
60
61 protected <Buffer> CLMemory(final CLContext context, final long size, final long id, final int flags) {
62 this(context, null, size, id, flags);
63 }
64
65 protected CLMemory(final CLContext context, final B directBuffer, final long size, final long id, final int flags) {
66 super(context, id);
67 this.buffer = directBuffer;
68 this.FLAGS = flags;
69 this.size = size;
70 this.binding = context.getPlatform().getCLBinding();
71 initElementSize();
73 }
74
75 private void initElementSize() {
76 this.elementSize = (buffer==null) ? 1 : Buffers.sizeOfBufferElem(buffer);
77 }
78
79 protected final void initCLCapacity() {
80 this.clCapacity = (int) (size / elementSize);
81 }
82
83 /**
84 * Returns true if a host pointer must be specified on mem object creation.
85 */
86 protected static boolean isHostPointerFlag(final int flags) {
87 return (flags & CL_MEM_COPY_HOST_PTR) != 0
88 || (flags & CL_MEM_USE_HOST_PTR) != 0;
89 }
90
91 protected static long getSizeImpl(final CLContext context, final long id) {
92 final PointerBuffer pb = PointerBuffer.allocateDirect(1);
93 final CL binding = context.getPlatform().getCLBinding(); // FIXME: CL separation makes this pretty complicated !
94 final int ret = binding.clGetMemObjectInfo(id, CL_MEM_SIZE, pb.elementSize(), pb.getBuffer(), null);
95 checkForError(ret, "can not obtain buffer info");
96 return pb.get();
97 }
98
99 protected static CL getCL(final CLContext context) {
100 return context.getCL();
101 }
102
103 /**
104 * Registers a callback which will be called by the OpenCL implementation
105 * when the memory object is released.
106 */
109 @Override
110 public void memoryDeallocated(final long memObjID) {
111 listener.memoryDeallocated(CLMemory.this);
112 }
113 });
114 }
115
116 /**
117 * Returns a new instance of CLMemory pointing to the same CLResource but using a different Buffer.
118 */
119 public abstract <T extends Buffer> CLMemory<T> cloneWith(T directBuffer);
120
121
122 public CLMemory<B> use(final B buffer) {
123 if(this.buffer != null && buffer != null && this.buffer.getClass() != buffer.getClass()) {
124 throw new IllegalArgumentException(
125 "expected a Buffer of class " + this.buffer.getClass()
126 +" but got " + buffer.getClass());
127 }
128 this.buffer = buffer;
129 initElementSize();
131 return this;
132 }
133
134 /**
135 * Returns the optional NIO buffer for this memory object.
136 */
137 public B getBuffer() {
138 return buffer;
139 }
140
141 /**
142 * Returns the capacity of the wrapped direct buffer or 0 if no buffer available.
143 */
144 public int getNIOCapacity() {
145 if(buffer == null) {
146 return 0;
147 }
148 return buffer.limit();
149 }
150
151 /**
152 * Returns the size of the wrapped direct buffer in byte or 0 if no buffer available.
153 */
154 public int getNIOSize() {
155 if(buffer == null) {
156 return 0;
157 }
158 return getElementSize() * buffer.limit();
159 }
160
161 /**
162 * Returns the size of the allocated OpenCL memory in bytes.
163 */
164 public long getCLSize() {
165 return size;
166 }
167
168 /**
169 * Returns the size in buffer elements of this memory object.
170 */
171 public int getCLCapacity() {
172 return clCapacity;
173 }
174
175 /**
176 * Returns the size in bytes of a single buffer element.
177 * This method returns 1 if no buffer is available indicating regular byte access.
178 */
179 public int getElementSize() {
180 return elementSize;
181 }
182
183 /**
184 * Returns the configuration of this memory object.
185 */
186 public EnumSet<Mem> getConfig() {
187 return Mem.valuesOf(FLAGS);
188 }
189
190 /**
191 * Returns the number of buffer mappings. The map count returned should be considered immediately stale.
192 * It is unsuitable for general use in applications. This feature is provided for debugging.
193 */
194 public int getMapCount() {
195 final IntBuffer value = Buffers.newDirectIntBuffer(1);
196 final int ret = binding.clGetMemObjectInfo(ID, CL_MEM_MAP_COUNT, 4, value, null);
197 checkForError(ret, "can not obtain buffer map count.");
198 return value.get();
199 }
200
201 /**
202 * Returns true if this memory object was created with the {@link Mem#READ_ONLY} flag.
203 */
204 public boolean isReadOnly() {
205 return (Mem.READ_ONLY.CONFIG & FLAGS) != 0;
206 }
207
208 /**
209 * Returns true if this memory object was created with the {@link Mem#WRITE_ONLY} flag.
210 */
211 public boolean isWriteOnly() {
212 return (Mem.WRITE_ONLY.CONFIG & FLAGS) != 0;
213 }
214
215 /**
216 * Returns true if this memory object was created with the {@link Mem#READ_WRITE} flag.
217 */
218 public boolean isReadWrite() {
219 return (Mem.READ_WRITE.CONFIG & FLAGS) != 0;
220 }
221
222 @Override
223 public void release() {
224 super.release();
225 final int ret = binding.clReleaseMemObject(ID);
226 context.onMemoryReleased(this);
227 if(ret != CL_SUCCESS) {
228 throw newException(ret, "can not release "+this);
229 }
230 }
231
232 // TODO kept only temporary for debugging purposes
233 /**
234 * Returns the OpenGL buffer type of this shared buffer.
235 */
236// @Deprecated
237// /*public*/ final GLObjectType _getGLObjectType() {
238// int[] array = new int[1];
239// int ret = ((CLGL)cl).clGetGLObjectInfo(ID, array, 0, null, 0);
240// CLException.checkForError(ret, "error while asking for gl object info");
241// return GLObjectType.valueOf(array[0]);
242// }
243//
244// /**
245// * Returns the OpenGL object id of this shared buffer.
246// */
247// @Deprecated
248// /*public*/ final int _getGLObjectID() {
249// int[] array = new int[1];
250// int ret = ((CLGL)cl).clGetGLObjectInfo(ID, null, 0, array, 0);
251// CLException.checkForError(ret, "error while asking for gl object info");
252// return array[0];
253// }
254
255 @Override
256 public boolean equals(final Object obj) {
257 if (obj == null) {
258 return false;
259 }
260 if (getClass() != obj.getClass()) {
261 return false;
262 }
263 final CLMemory<?> other = (CLMemory<?>) obj;
264 if (this.ID != other.ID) {
265 return false;
266 }
267 if (this.context != other.context && (this.context == null || !this.context.equals(other.context))) {
268 return false;
269 }
270 return true;
271 }
272
273 @Override
274 public int hashCode() {
275 int hash = 7;
276 hash = 83 * hash + (int) (this.ID ^ (this.ID >>> 32));
277 hash = 83 * hash + (this.context != null ? this.context.hashCode() : 0);
278 return hash;
279 }
280
281 @Override
282 public String toString() {
283 return getClass().getSimpleName()+" [id: " + ID+" buffer: "+buffer+"]";
284 }
285
286 /**
287 * Memory settings for configuring CLMemory.
288 */
289 public enum Mem {
290
291 /**
292 * Enum representing CL_MEM_READ_WRITE.
293 * This flag specifies that the memory object will be read and
294 * written by a kernel.
295 */
296 READ_WRITE(CL_MEM_READ_WRITE),
297
298 /**
299 * Enum representing CL_MEM_WRITE_ONLY.
300 * This flags specifies that the memory object will be written
301 * but not read by a kernel.
302 * Reading from a buffer or image object created with WRITE_ONLY
303 * inside a kernel is undefined.
304 */
305 WRITE_ONLY(CL_MEM_WRITE_ONLY),
306
307 /**
308 * Enum representing CL_MEM_READ_ONLY.
309 * This flag specifies that the memory object is a read-only memory
310 * object when used inside a kernel. Writing to a buffer or image object
311 * created withREAD_ONLY inside a kernel is undefined.
312 */
313 READ_ONLY(CL_MEM_READ_ONLY),
314
315 /**
316 * Enum representing CL_MEM_USE_HOST_PTR.
317 * If specified, it indicates that the application wants the OpenCL
318 * implementation to use memory referenced by host_ptr as the storage
319 * bits for the memory object. OpenCL implementations are allowed
320 * to cache the buffer contents pointed to by host_ptr in device memory.
321 * This cached copy can be used when kernels are executed on a device.
322 */
323 USE_BUFFER(CL_MEM_USE_HOST_PTR),
324
325 /**
326 * Enum representing CL_MEM_ALLOC_HOST_PTR.
327 * This flag specifies that the application wants the OpenCL implementation
328 * to allocate memory from host accessible memory.
329 * {@link #ALLOCATE_BUFFER} and {@link #USE_BUFFER} are mutually exclusive.
330 */
331 ALLOCATE_BUFFER(CL_MEM_ALLOC_HOST_PTR),
332
333 /**
334 * Enum representing CL_MEM_COPY_HOST_PTR.
335 * If {@link #COPY_BUFFER} specified, it indicates that the application
336 * wants the OpenCL implementation to allocate memory for the memory object
337 * and copy the data from memory referenced by host_ptr.<br/>
338 * {@link #COPY_BUFFER} and {@link #USE_BUFFER} are mutually exclusive.
339 */
340 COPY_BUFFER(CL_MEM_COPY_HOST_PTR);
341
342 /**
343 * Value of wrapped OpenCL flag.
344 */
345 public final int CONFIG;
346
347 private Mem(final int config) {
348 this.CONFIG = config;
349 }
350
351 public static Mem valueOf(final int bufferFlag) {
352 switch (bufferFlag) {
353 case CL_MEM_READ_WRITE:
354 return Mem.READ_WRITE;
355 case CL_MEM_READ_ONLY:
356 return Mem.READ_ONLY;
357 case CL_MEM_WRITE_ONLY:
358 return Mem.WRITE_ONLY;
359 case CL_MEM_USE_HOST_PTR:
360 return Mem.USE_BUFFER;
361 case(CL_MEM_ALLOC_HOST_PTR):
362 return ALLOCATE_BUFFER;
363 case CL_MEM_COPY_HOST_PTR:
364 return Mem.COPY_BUFFER;
365 }
366 return null;
367 }
368
369 public static EnumSet<Mem> valuesOf(final int bitfield) {
370 final List<Mem> matching = new ArrayList<Mem>();
371 final Mem[] values = Mem.values();
372 for (final Mem value : values) {
373 if((value.CONFIG & bitfield) != 0)
374 matching.add(value);
375 }
376 if(matching.isEmpty())
377 return EnumSet.noneOf(Mem.class);
378 else
379 return EnumSet.copyOf(matching);
380 }
381
382 public static int flagsToInt(final Mem[] flags) {
383 int clFlags = 0;
384 if (flags != null) {
385 for (int i = 0; i < flags.length; i++) {
386 clFlags |= flags[i].CONFIG;
387 }
388 }
389 if (clFlags == 0) {
390 clFlags = CL_MEM_READ_WRITE;
391 }
392 return clFlags;
393 }
394 }
395
396 /**
397 * Configures the mapping process.
398 * @see com.jogamp.opencl.CLCommandQueue#putMapBuffer(CLBuffer, com.jogamp.opencl.CLMemory.Map, boolean).
399 * @see com.jogamp.opencl.CLCommandQueue#putMapImage(CLImage2d, com.jogamp.opencl.CLMemory.Map, boolean)
400 * @see com.jogamp.opencl.CLCommandQueue#putMapImage(CLImage3d, com.jogamp.opencl.CLMemory.Map, boolean)
401 */
402 public enum Map {
403
404 /**
405 * Enum representing CL_MAP_READ | CL_MAP_WRITE.
406 * This flag specifies that the memory object will be mapped for read and write operation.
407 */
408 READ_WRITE(CL_MAP_READ | CL_MAP_WRITE),
409
410 /**
411 * Enum representing CL_MAP_WRITE.
412 * This flag specifies that the memory object will be mapped for write operation.
413 */
414 WRITE(CL_MAP_WRITE),
415
416 /**
417 * Enum representing CL_MAP_READ.
418 * This flag specifies that the memory object will be mapped for read operation.
419 */
420 READ(CL_MAP_READ);
421
422 /**
423 * Value of wrapped OpenCL flag.
424 */
425 public final int FLAGS;
426
427 private Map(final int flags) {
428 this.FLAGS = flags;
429 }
430
431 public Map valueOf(final int flag) {
432 if(flag == WRITE.FLAGS)
433 return WRITE;
434 else if(flag == READ.FLAGS)
435 return READ;
436 else if(flag == READ_WRITE.FLAGS)
437 return READ_WRITE;
438 return null;
439 }
440
441 }
442
443 public enum GLObjectType {
444
445 GL_OBJECT_BUFFER(CL_GL_OBJECT_BUFFER),
446 GL_OBJECT_TEXTURE2D(CL_GL_OBJECT_TEXTURE2D),
447 GL_OBJECT_TEXTURE3D(CL_GL_OBJECT_TEXTURE3D),
448 GL_OBJECT_RENDERBUFFER(CL_GL_OBJECT_RENDERBUFFER);
449
450 public final int TYPE;
451
452 private GLObjectType(final int type) {
453 this.TYPE = type;
454 }
455
456 public static GLObjectType valueOf(final int type) {
457 if(type == CL_GL_OBJECT_BUFFER)
458 return GL_OBJECT_BUFFER;
459 else if(type == CL_GL_OBJECT_TEXTURE2D)
460 return GL_OBJECT_TEXTURE2D;
461 else if(type == CL_GL_OBJECT_TEXTURE3D)
462 return GL_OBJECT_TEXTURE3D;
463 else if(type == CL_GL_OBJECT_RENDERBUFFER)
464 return GL_OBJECT_RENDERBUFFER;
465 return null;
466 }
467 }
468
469}
CLContext is responsible for managing objects such as command-queues, memory, program and kernel obje...
Definition: CLContext.java:79
CL getCL()
Return the low level OpenCL interface.
Definition: CLContext.java:646
CLPlatform getPlatform()
Returns the CLPlatform this context is running on.
Definition: CLContext.java:569
Common superclass for all OpenCL memory types.
Definition: CLMemory.java:49
final void initCLCapacity()
Definition: CLMemory.java:79
int getElementSize()
Returns the size in bytes of a single buffer element.
Definition: CLMemory.java:179
int getMapCount()
Returns the number of buffer mappings.
Definition: CLMemory.java:194
boolean equals(final Object obj)
Returns the OpenGL buffer type of this shared buffer.
Definition: CLMemory.java:256
static CL getCL(final CLContext context)
Definition: CLMemory.java:99
int getCLCapacity()
Returns the size in buffer elements of this memory object.
Definition: CLMemory.java:171
boolean isReadWrite()
Returns true if this memory object was created with the Mem#READ_WRITE flag.
Definition: CLMemory.java:218
B getBuffer()
Returns the optional NIO buffer for this memory object.
Definition: CLMemory.java:137
int getNIOCapacity()
Returns the capacity of the wrapped direct buffer or 0 if no buffer available.
Definition: CLMemory.java:144
static boolean isHostPointerFlag(final int flags)
Returns true if a host pointer must be specified on mem object creation.
Definition: CLMemory.java:86
boolean isReadOnly()
Returns true if this memory object was created with the Mem#READ_ONLY flag.
Definition: CLMemory.java:204
CLMemory(final CLContext context, final B directBuffer, final long size, final long id, final int flags)
Definition: CLMemory.java:65
CLMemory< B > use(final B buffer)
Definition: CLMemory.java:122
void registerDestructorCallback(final CLMemObjectListener listener)
Registers a callback which will be called by the OpenCL implementation when the memory object is rele...
Definition: CLMemory.java:107
int getNIOSize()
Returns the size of the wrapped direct buffer in byte or 0 if no buffer available.
Definition: CLMemory.java:154
static long getSizeImpl(final CLContext context, final long id)
Definition: CLMemory.java:91
EnumSet< Mem > getConfig()
Returns the configuration of this memory object.
Definition: CLMemory.java:186
long getCLSize()
Returns the size of the allocated OpenCL memory in bytes.
Definition: CLMemory.java:164
void release()
Releases the OpenCL resource.
Definition: CLMemory.java:223
boolean isWriteOnly()
Returns true if this memory object was created with the Mem#WRITE_ONLY flag.
Definition: CLMemory.java:211
abstract< T extends Buffer > CLMemory< T > cloneWith(T directBuffer)
Returns a new instance of CLMemory pointing to the same CLResource but using a different Buffer.
final long ID
The OpenCL object handle.
Definition: CLObject.java:41
static GLObjectType valueOf(final int type)
Definition: CLMemory.java:456
Configures the mapping process.
Definition: CLMemory.java:402
READ
Enum representing CL_MAP_READ.
Definition: CLMemory.java:420
Map valueOf(final int flag)
Definition: CLMemory.java:431
final int FLAGS
Value of wrapped OpenCL flag.
Definition: CLMemory.java:425
WRITE
Enum representing CL_MAP_WRITE.
Definition: CLMemory.java:414
READ_WRITE
Enum representing CL_MAP_READ | CL_MAP_WRITE.
Definition: CLMemory.java:408
Memory settings for configuring CLMemory.
Definition: CLMemory.java:289
static int flagsToInt(final Mem[] flags)
Definition: CLMemory.java:382
WRITE_ONLY
Enum representing CL_MEM_WRITE_ONLY.
Definition: CLMemory.java:305
READ_WRITE
Enum representing CL_MEM_READ_WRITE.
Definition: CLMemory.java:296
ALLOCATE_BUFFER
Enum representing CL_MEM_ALLOC_HOST_PTR.
Definition: CLMemory.java:331
final int CONFIG
Value of wrapped OpenCL flag.
Definition: CLMemory.java:345
static EnumSet< Mem > valuesOf(final int bitfield)
Definition: CLMemory.java:369
COPY_BUFFER
Enum representing CL_MEM_COPY_HOST_PTR.
Definition: CLMemory.java:340
USE_BUFFER
Enum representing CL_MEM_USE_HOST_PTR.
Definition: CLMemory.java:323
READ_ONLY
Enum representing CL_MEM_READ_ONLY.
Definition: CLMemory.java:313
static Mem valueOf(final int bufferFlag)
Definition: CLMemory.java:351
A callback which is invoked by the OpenCL implementation when the memory object is deleted and its re...
void memoryDeallocated(CLMemory<?> mem)
Java bindings to OpenCL, the Open Computing Language.
Definition: CL.java:26
int clReleaseMemObject(long memobj)
Interface to C language function: cl_int {@native clReleaseMemObject}(cl_mem memobj)
int clSetMemObjectDestructorCallback(long memObjID, CLMemObjectDestructorCallback cb)
Interface to C language function: int32_t {@native clSetMemObjectDestructorCallback}(cl_mem memobj...
int clGetMemObjectInfo(long memobj, int param_name, long param_value_size, Buffer param_value, PointerBuffer param_value_size_ret)
Interface to C language function: cl_int {@native clGetMemObjectInfo}(cl_mem memobj,...
A callback which is invoked by the OpenCL implementation when the memory object is deleted and its re...