JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLArrayData.java
Go to the documentation of this file.
1/**
2 * Copyright 2010-2023 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.opengl;
30
31import java.nio.Buffer;
32
33import com.jogamp.opengl.fixedfunc.GLPointerFunc;
34
35/**
36 *
37 * The total number of bytes hold by the referenced buffer is:
38 * getComponentSize()* getComponentNumber() * getElementNumber()
39 *
40 */
41public interface GLArrayData {
42 /**
43 * Implementation and type dependent object association.
44 * <p>
45 * One currently known use case is to associate a {@link com.jogamp.opengl.util.glsl.ShaderState ShaderState}
46 * to an GLSL aware vertex attribute object, allowing to use the ShaderState to handle it's
47 * data persistence, location and state change.<br/>
48 * This is implicitly done via {@link com.jogamp.opengl.util.glsl.ShaderState#ownAttribute(GLArrayData, boolean) shaderState.ownAttribute(GLArrayData, boolean)}.
49 * </p>
50 * @param obj implementation and type dependent association
51 * @param enable pass true to enable the association and false to disable it.
52 */
53 public void associate(Object obj, boolean enable);
54
55 /**
56 * Returns true if this data set is intended for a GLSL vertex shader attribute,
57 * otherwise false, ie intended for fixed function vertex pointer
58 */
59 public boolean isVertexAttribute();
60
61 /**
62 * The index of the predefined array index, see list below,
63 * or -1 in case of a shader attribute array.
64 *
65 * @see GLPointerFunc#GL_VERTEX_ARRAY
66 * @see GLPointerFunc#GL_NORMAL_ARRAY
67 * @see GLPointerFunc#GL_COLOR_ARRAY
68 * @see GLPointerFunc#GL_TEXTURE_COORD_ARRAY
69 */
70 public int getIndex();
71
72 /**
73 * The name of the reflecting shader array attribute.
74 */
75 public String getName();
76
77 /**
78 * Set a new name for this array.
79 * <p>
80 * This clears the location, i.e. sets it to -1.
81 * </p>
82 * @see #setLocation(int)
83 * @see #setLocation(GL2ES2, int)
84 */
85 public void setName(String newName);
86
87
88 /**
89 * Returns the shader attribute location for this name,
90 * -1 if not yet determined
91 */
92 public int getLocation();
93
94 /**
95 * Sets the given location of the shader attribute
96 *
97 * @return the given location
98 * @see com.jogamp.opengl.util.glsl.ShaderState#vertexAttribPointer(GL2ES2, GLArrayData)
99 */
100 public int setLocation(int v);
101
102 /**
103 * Retrieves the location of the shader attribute from the linked shader program.
104 * <p>
105 * No validation is performed within the implementation.
106 * </p>
107 * @param gl
108 * @param program
109 * @return &ge;0 denotes a valid attribute location as found and used in the given shader program.
110 * &lt;0 denotes an invalid location, i.e. not found or used in the given shader program.
111 */
112 public int setLocation(GL2ES2 gl, int program);
113
114 /**
115 * Binds the location of the shader attribute to the given location for the unlinked shader program.
116 * <p>
117 * No validation is performed within the implementation.
118 * </p>
119 * @param gl
120 * @param program
121 * @return the given location
122 */
123 public int setLocation(GL2ES2 gl, int program, int location);
124
125 /**
126 * Determines whether the data is server side (VBO) and enabled,
127 * or a client side array (false).
128 */
129 public boolean isVBO();
130
131 /**
132 * The VBO buffer offset or 0 if not a VBO
133 */
134 public long getVBOOffset();
135
136 /**
137 * The VBO name or 0 if not a VBO
138 */
139 public int getVBOName();
140
141 /**
142 * The VBO usage or 0 if not a VBO
143 * @return 0 if not a GPU buffer, otherwise {@link GL2ES2#GL_STREAM_DRAW}, {@link GL#GL_STATIC_DRAW} or {@link GL#GL_DYNAMIC_DRAW}
144 */
145 public int getVBOUsage();
146
147 /**
148 * The VBO target or 0 if not a VBO
149 * @return 0 if not a GPU buffer, otherwise {@link GL#GL_ARRAY_BUFFER} or {@link GL#GL_ELEMENT_ARRAY_BUFFER}
150 */
151 public int getVBOTarget();
152
153
154 /**
155 * The Buffer holding the data, may be null if a GPU buffer without client bound data
156 */
157 public Buffer getBuffer();
158
159 /**
160 * The number of components per element
161 */
162 public int getCompsPerElem();
163
164 /**
165 * The component's GL data type, ie. GL_FLOAT
166 */
167 public int getCompType();
168
169 /**
170 * The component's size in bytes
171 */
172 public int getBytesPerComp();
173
174 /**
175 * Returns true if data has been {@link com.jogamp.opengl.util.GLArrayDataEditable#seal(boolean) sealed} (flipped to read), otherwise false (writing mode).
176 *
177 * @see com.jogamp.opengl.util.GLArrayDataEditable#seal(boolean)
178 * @see com.jogamp.opengl.util.GLArrayDataEditable#seal(GL, boolean)
179 */
180 public boolean sealed();
181
182 /**
183 * Returns the element position (written elements) if not {@link #sealed()} or
184 * the element limit (available to read) after {@link #sealed()} (flip).
185 * <p>
186 * On element consist out of {@link #getCompsPerElem()} components.
187 * </p>
188 * @see #sealed()
189 * @see #getByteCount()
190 * @see #elemPosition()
191 * @see #remainingElems()
192 * @see #getElemCapacity()
193 */
194 public int getElemCount();
195
196 /**
197 * Returns the element position.
198 * <p>
199 * On element consist out of {@link #getCompsPerElem()} components.
200 * </p>
201 * @see #bytePosition()
202 * @see #getElemCount()
203 * @see #remainingElems()
204 * @see #getElemCapacity()
205 */
206 public int elemPosition();
207
208 /**
209 * The current number of remaining elements.
210 * <p>
211 * On element consist out of {@link #getCompsPerElem()} components.
212 * </p>
213 * Returns the number of elements between the current position and the limit, i.e. remaining elements to write in this buffer.
214 * @see #remainingBytes()
215 * @see #getElemCount()
216 * @see #elemPosition()
217 * @see #getElemCapacity()
218 */
219 public int remainingElems();
220
221 /**
222 * Return the element capacity.
223 * <p>
224 * On element consist out of {@link #getCompsPerElem()} components.
225 * </p>
226 * @see #getByteCapacity()
227 * @see #getElemCount()
228 * @see #elemPosition()
229 * @see #remainingElems()
230 */
231 public int getElemCapacity();
232
233 /**
234 * Returns the byte position (written elements) if not {@link #sealed()} or
235 * the byte limit (available to read) after {@link #sealed()} (flip).
236 * @see #sealed()
237 * @see #getElemCount()
238 * @see #bytePosition()
239 * @see #remainingBytes()
240 * @see #getByteCapacity()
241 */
242 public int getByteCount();
243
244 /**
245 * Returns the bytes position.
246 * @see #elemPosition()
247 * @see #getByteCount()
248 * @see #remainingElems()
249 * @see #getElemCapacity()
250 */
251 public int bytePosition();
252
253 /**
254 * The current number of remaining bytes.
255 * <p>
256 * Returns the number of bytes between the current position and the limit, i.e. remaining bytes to write in this buffer.
257 * </p>
258 * @see #remainingElems()
259 * @see #getByteCount()
260 * @see #bytePosition()
261 * @see #getByteCapacity()
262 */
263 public int remainingBytes();
264
265 /**
266 * Return the capacity in bytes.
267 * @see #getElemCapacity()
268 * @see #getByteCount()
269 * @see #bytePosition()
270 * @see #remainingBytes()
271 */
272 public int getByteCapacity();
273
274 /** Returns a string with detailed buffer fill stats. */
275 public String fillStatsToString();
276 /** Returns a string with detailed buffer element stats, i.e. sealed, count, position, remaining, limit and capacity. */
277 public String elemStatsToString();
278
279 /**
280 * True, if GL shall normalize fixed point data while converting
281 * them into float.
282 * <p>
283 * Default behavior (of the fixed function pipeline) is <code>true</code>
284 * for fixed point data type and <code>false</code> for floating point data types.
285 * </p>
286 */
287 public boolean getNormalized();
288
289 /**
290 * @return the byte offset between consecutive components
291 */
292 public int getStride();
293
294 @Override
295 public String toString();
296
297 public void destroy(GL gl);
298
299}
300
The total number of bytes hold by the referenced buffer is: getComponentSize()* getComponentNumber() ...
int remainingElems()
The current number of remaining elements.
void setName(String newName)
Set a new name for this array.
boolean sealed()
Returns true if data has been sealed (flipped to read), otherwise false (writing mode).
int getVBOTarget()
The VBO target or 0 if not a VBO.
int getCompsPerElem()
The number of components per element.
int getIndex()
The index of the predefined array index, see list below, or -1 in case of a shader attribute array.
String elemStatsToString()
Returns a string with detailed buffer element stats, i.e.
String fillStatsToString()
Returns a string with detailed buffer fill stats.
long getVBOOffset()
The VBO buffer offset or 0 if not a VBO.
int getElemCapacity()
Return the element capacity.
boolean getNormalized()
True, if GL shall normalize fixed point data while converting them into float.
int setLocation(int v)
Sets the given location of the shader attribute.
boolean isVBO()
Determines whether the data is server side (VBO) and enabled, or a client side array (false).
int getVBOUsage()
The VBO usage or 0 if not a VBO.
String getName()
The name of the reflecting shader array attribute.
Buffer getBuffer()
The Buffer holding the data, may be null if a GPU buffer without client bound data.
int bytePosition()
Returns the bytes position.
boolean isVertexAttribute()
Returns true if this data set is intended for a GLSL vertex shader attribute, otherwise false,...
int getElemCount()
Returns the element position (written elements) if not sealed() or the element limit (available to re...
int elemPosition()
Returns the element position.
int getVBOName()
The VBO name or 0 if not a VBO.
int getBytesPerComp()
The component's size in bytes.
int setLocation(GL2ES2 gl, int program, int location)
Binds the location of the shader attribute to the given location for the unlinked shader program.
int getByteCapacity()
Return the capacity in bytes.
int remainingBytes()
The current number of remaining bytes.
void associate(Object obj, boolean enable)
Implementation and type dependent object association.
int setLocation(GL2ES2 gl, int program)
Retrieves the location of the shader attribute from the linked shader program.
int getCompType()
The component's GL data type, ie.
int getLocation()
Returns the shader attribute location for this name, -1 if not yet determined.
int getByteCount()
Returns the byte position (written elements) if not sealed() or the byte limit (available to read) af...