Element.java revision 4ef6650bd05a39a09958ea1db92f120ea4949cb1
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.renderscript; 18 19import java.lang.reflect.Field; 20import android.util.Log; 21 22/** 23 * @hide 24 * 25 * Element is the basic data type of RenderScript. An element can be of 2 26 * forms. Basic elements contain a single component of data. This can be of 27 * any of the legal RS types. Examples of basic element types. 28 * Single float value 29 * 4 element float vector 30 * single RGB-565 color 31 * single unsigned int 16 32 * 33 * Complex elements will contain a list of sub-elements and names. This in 34 * effect represents a structure of data. The fields can be accessed by name 35 * from a script or shader. The memory layout is defined and ordered. Data 36 * alignment is determinied by the most basic primitive type. i.e. a float4 37 * vector will be alligned to sizeof(float) and not sizeof(float4). The 38 * ordering of elements in memory will be the order in which they were added 39 * with each component aligned as necessary. No re-ordering will be done. 40 * 41 * The primary source of elements will be from scripts. A script that exports a 42 * bind point for a data structure will generate a RS element to represent the 43 * data exported by the script. 44 **/ 45public class Element extends BaseObj { 46 int mSize; 47 Element[] mElements; 48 String[] mElementNames; 49 int[] mArraySizes; 50 51 DataType mType; 52 DataKind mKind; 53 boolean mNormalized; 54 int mVectorSize; 55 56 int getSizeBytes() {return mSize;} 57 58 59 /** 60 * DataType represents the basic type information for a basic element. The 61 * naming convention follows. For numeric types its FLOAT, SIGNED, UNSIGNED 62 * followed by the _BITS where BITS is the size of the data. BOOLEAN is a 63 * true / false (1,0) represented in an 8 bit container. The UNSIGNED 64 * variants with multiple bit definitions are for packed graphical data 65 * formats and represents vectors with per vector member sizes which are 66 * treated as a single unit for packing and alignment purposes. 67 * 68 * MATRIX the three matrix types contain FLOAT_32 elements and are treated 69 * as 32 bits for alignment purposes. 70 * 71 * RS_* objects. 32 bit opaque handles. 72 */ 73 public enum DataType { 74 //FLOAT_16 (1, 2), 75 FLOAT_32 (2, 4), 76 FLOAT_64 (3, 8), 77 SIGNED_8 (4, 1), 78 SIGNED_16 (5, 2), 79 SIGNED_32 (6, 4), 80 SIGNED_64 (7, 8), 81 UNSIGNED_8 (8, 1), 82 UNSIGNED_16 (9, 2), 83 UNSIGNED_32 (10, 4), 84 UNSIGNED_64 (11, 8), 85 86 BOOLEAN(12, 1), 87 88 UNSIGNED_5_6_5 (13, 2), 89 UNSIGNED_5_5_5_1 (14, 2), 90 UNSIGNED_4_4_4_4 (15, 2), 91 92 MATRIX_4X4 (16, 64), 93 MATRIX_3X3 (17, 36), 94 MATRIX_2X2 (18, 16), 95 96 RS_ELEMENT (1000, 4), 97 RS_TYPE (1001, 4), 98 RS_ALLOCATION (1002, 4), 99 RS_SAMPLER (1003, 4), 100 RS_SCRIPT (1004, 4), 101 RS_MESH (1005, 4), 102 RS_PROGRAM_FRAGMENT (1006, 4), 103 RS_PROGRAM_VERTEX (1007, 4), 104 RS_PROGRAM_RASTER (1008, 4), 105 RS_PROGRAM_STORE (1009, 4); 106 107 int mID; 108 int mSize; 109 DataType(int id, int size) { 110 mID = id; 111 mSize = size; 112 } 113 } 114 115 /** 116 * The special interpretation of the data if required. This is primarly 117 * useful for graphical data. USER indicates no special interpretation is 118 * expected. PIXEL is used in conjunction with the standard data types for 119 * representing texture formats. 120 */ 121 public enum DataKind { 122 USER (0), 123 124 PIXEL_L (7), 125 PIXEL_A (8), 126 PIXEL_LA (9), 127 PIXEL_RGB (10), 128 PIXEL_RGBA (11); 129 130 int mID; 131 DataKind(int id) { 132 mID = id; 133 } 134 } 135 136 /** 137 * Return if a element is too complex for use as a data source for a Mesh or 138 * a Program. 139 * 140 * @return boolean 141 */ 142 public boolean isComplex() { 143 if (mElements == null) { 144 return false; 145 } 146 for (int ct=0; ct < mElements.length; ct++) { 147 if (mElements[ct].mElements != null) { 148 return true; 149 } 150 } 151 return false; 152 } 153 154 /** 155 * Utility function for returning an Element containing a single Boolean. 156 * 157 * @param rs Context to which the element will belong. 158 * 159 * @return Element 160 */ 161 public static Element BOOLEAN(RenderScript rs) { 162 if(rs.mElement_BOOLEAN == null) { 163 rs.mElement_BOOLEAN = createUser(rs, DataType.BOOLEAN); 164 } 165 return rs.mElement_BOOLEAN; 166 } 167 168 /** 169 * Utility function for returning an Element containing a single UNSIGNED_8. 170 * 171 * @param rs Context to which the element will belong. 172 * 173 * @return Element 174 */ 175 public static Element U8(RenderScript rs) { 176 if(rs.mElement_U8 == null) { 177 rs.mElement_U8 = createUser(rs, DataType.UNSIGNED_8); 178 } 179 return rs.mElement_U8; 180 } 181 182 /** 183 * Utility function for returning an Element containing a single SIGNED_8. 184 * 185 * @param rs Context to which the element will belong. 186 * 187 * @return Element 188 */ 189 public static Element I8(RenderScript rs) { 190 if(rs.mElement_I8 == null) { 191 rs.mElement_I8 = createUser(rs, DataType.SIGNED_8); 192 } 193 return rs.mElement_I8; 194 } 195 196 public static Element U16(RenderScript rs) { 197 if(rs.mElement_U16 == null) { 198 rs.mElement_U16 = createUser(rs, DataType.UNSIGNED_16); 199 } 200 return rs.mElement_U16; 201 } 202 203 public static Element I16(RenderScript rs) { 204 if(rs.mElement_I16 == null) { 205 rs.mElement_I16 = createUser(rs, DataType.SIGNED_16); 206 } 207 return rs.mElement_I16; 208 } 209 210 public static Element U32(RenderScript rs) { 211 if(rs.mElement_U32 == null) { 212 rs.mElement_U32 = createUser(rs, DataType.UNSIGNED_32); 213 } 214 return rs.mElement_U32; 215 } 216 217 public static Element I32(RenderScript rs) { 218 if(rs.mElement_I32 == null) { 219 rs.mElement_I32 = createUser(rs, DataType.SIGNED_32); 220 } 221 return rs.mElement_I32; 222 } 223 224 public static Element U64(RenderScript rs) { 225 if(rs.mElement_U64 == null) { 226 rs.mElement_U64 = createUser(rs, DataType.UNSIGNED_64); 227 } 228 return rs.mElement_U64; 229 } 230 231 public static Element I64(RenderScript rs) { 232 if(rs.mElement_I64 == null) { 233 rs.mElement_I64 = createUser(rs, DataType.SIGNED_64); 234 } 235 return rs.mElement_I64; 236 } 237 238 public static Element F32(RenderScript rs) { 239 if(rs.mElement_F32 == null) { 240 rs.mElement_F32 = createUser(rs, DataType.FLOAT_32); 241 } 242 return rs.mElement_F32; 243 } 244 245 public static Element F64(RenderScript rs) { 246 if(rs.mElement_F64 == null) { 247 rs.mElement_F64 = createUser(rs, DataType.FLOAT_64); 248 } 249 return rs.mElement_F64; 250 } 251 252 public static Element ELEMENT(RenderScript rs) { 253 if(rs.mElement_ELEMENT == null) { 254 rs.mElement_ELEMENT = createUser(rs, DataType.RS_ELEMENT); 255 } 256 return rs.mElement_ELEMENT; 257 } 258 259 public static Element TYPE(RenderScript rs) { 260 if(rs.mElement_TYPE == null) { 261 rs.mElement_TYPE = createUser(rs, DataType.RS_TYPE); 262 } 263 return rs.mElement_TYPE; 264 } 265 266 public static Element ALLOCATION(RenderScript rs) { 267 if(rs.mElement_ALLOCATION == null) { 268 rs.mElement_ALLOCATION = createUser(rs, DataType.RS_ALLOCATION); 269 } 270 return rs.mElement_ALLOCATION; 271 } 272 273 public static Element SAMPLER(RenderScript rs) { 274 if(rs.mElement_SAMPLER == null) { 275 rs.mElement_SAMPLER = createUser(rs, DataType.RS_SAMPLER); 276 } 277 return rs.mElement_SAMPLER; 278 } 279 280 public static Element SCRIPT(RenderScript rs) { 281 if(rs.mElement_SCRIPT == null) { 282 rs.mElement_SCRIPT = createUser(rs, DataType.RS_SCRIPT); 283 } 284 return rs.mElement_SCRIPT; 285 } 286 287 public static Element MESH(RenderScript rs) { 288 if(rs.mElement_MESH == null) { 289 rs.mElement_MESH = createUser(rs, DataType.RS_MESH); 290 } 291 return rs.mElement_MESH; 292 } 293 294 public static Element PROGRAM_FRAGMENT(RenderScript rs) { 295 if(rs.mElement_PROGRAM_FRAGMENT == null) { 296 rs.mElement_PROGRAM_FRAGMENT = createUser(rs, DataType.RS_PROGRAM_FRAGMENT); 297 } 298 return rs.mElement_PROGRAM_FRAGMENT; 299 } 300 301 public static Element PROGRAM_VERTEX(RenderScript rs) { 302 if(rs.mElement_PROGRAM_VERTEX == null) { 303 rs.mElement_PROGRAM_VERTEX = createUser(rs, DataType.RS_PROGRAM_VERTEX); 304 } 305 return rs.mElement_PROGRAM_VERTEX; 306 } 307 308 public static Element PROGRAM_RASTER(RenderScript rs) { 309 if(rs.mElement_PROGRAM_RASTER == null) { 310 rs.mElement_PROGRAM_RASTER = createUser(rs, DataType.RS_PROGRAM_RASTER); 311 } 312 return rs.mElement_PROGRAM_RASTER; 313 } 314 315 public static Element PROGRAM_STORE(RenderScript rs) { 316 if(rs.mElement_PROGRAM_STORE == null) { 317 rs.mElement_PROGRAM_STORE = createUser(rs, DataType.RS_PROGRAM_STORE); 318 } 319 return rs.mElement_PROGRAM_STORE; 320 } 321 322 323 public static Element A_8(RenderScript rs) { 324 if(rs.mElement_A_8 == null) { 325 rs.mElement_A_8 = createPixel(rs, DataType.UNSIGNED_8, DataKind.PIXEL_A); 326 } 327 return rs.mElement_A_8; 328 } 329 330 public static Element RGB_565(RenderScript rs) { 331 if(rs.mElement_RGB_565 == null) { 332 rs.mElement_RGB_565 = createPixel(rs, DataType.UNSIGNED_5_6_5, DataKind.PIXEL_RGB); 333 } 334 return rs.mElement_RGB_565; 335 } 336 337 public static Element RGB_888(RenderScript rs) { 338 if(rs.mElement_RGB_888 == null) { 339 rs.mElement_RGB_888 = createPixel(rs, DataType.UNSIGNED_8, DataKind.PIXEL_RGB); 340 } 341 return rs.mElement_RGB_888; 342 } 343 344 public static Element RGBA_5551(RenderScript rs) { 345 if(rs.mElement_RGBA_5551 == null) { 346 rs.mElement_RGBA_5551 = createPixel(rs, DataType.UNSIGNED_5_5_5_1, DataKind.PIXEL_RGBA); 347 } 348 return rs.mElement_RGBA_5551; 349 } 350 351 public static Element RGBA_4444(RenderScript rs) { 352 if(rs.mElement_RGBA_4444 == null) { 353 rs.mElement_RGBA_4444 = createPixel(rs, DataType.UNSIGNED_4_4_4_4, DataKind.PIXEL_RGBA); 354 } 355 return rs.mElement_RGBA_4444; 356 } 357 358 public static Element RGBA_8888(RenderScript rs) { 359 if(rs.mElement_RGBA_8888 == null) { 360 rs.mElement_RGBA_8888 = createPixel(rs, DataType.UNSIGNED_8, DataKind.PIXEL_RGBA); 361 } 362 return rs.mElement_RGBA_8888; 363 } 364 365 public static Element F32_2(RenderScript rs) { 366 if(rs.mElement_FLOAT_2 == null) { 367 rs.mElement_FLOAT_2 = createVector(rs, DataType.FLOAT_32, 2); 368 } 369 return rs.mElement_FLOAT_2; 370 } 371 372 public static Element F32_3(RenderScript rs) { 373 if(rs.mElement_FLOAT_3 == null) { 374 rs.mElement_FLOAT_3 = createVector(rs, DataType.FLOAT_32, 3); 375 } 376 return rs.mElement_FLOAT_3; 377 } 378 379 public static Element F32_4(RenderScript rs) { 380 if(rs.mElement_FLOAT_4 == null) { 381 rs.mElement_FLOAT_4 = createVector(rs, DataType.FLOAT_32, 4); 382 } 383 return rs.mElement_FLOAT_4; 384 } 385 386 public static Element U8_4(RenderScript rs) { 387 if(rs.mElement_UCHAR_4 == null) { 388 rs.mElement_UCHAR_4 = createVector(rs, DataType.UNSIGNED_8, 4); 389 } 390 return rs.mElement_UCHAR_4; 391 } 392 393 public static Element MATRIX_4X4(RenderScript rs) { 394 if(rs.mElement_MATRIX_4X4 == null) { 395 rs.mElement_MATRIX_4X4 = createUser(rs, DataType.MATRIX_4X4); 396 } 397 return rs.mElement_MATRIX_4X4; 398 } 399 public static Element MATRIX4X4(RenderScript rs) { 400 return MATRIX_4X4(rs); 401 } 402 403 public static Element MATRIX_3X3(RenderScript rs) { 404 if(rs.mElement_MATRIX_3X3 == null) { 405 rs.mElement_MATRIX_3X3 = createUser(rs, DataType.MATRIX_3X3); 406 } 407 return rs.mElement_MATRIX_4X4; 408 } 409 410 public static Element MATRIX_2X2(RenderScript rs) { 411 if(rs.mElement_MATRIX_2X2 == null) { 412 rs.mElement_MATRIX_2X2 = createUser(rs, DataType.MATRIX_2X2); 413 } 414 return rs.mElement_MATRIX_2X2; 415 } 416 417 Element(int id, RenderScript rs, Element[] e, String[] n, int[] as) { 418 super(id, rs); 419 mSize = 0; 420 mElements = e; 421 mElementNames = n; 422 mArraySizes = as; 423 for (int ct = 0; ct < mElements.length; ct++ ) { 424 mSize += mElements[ct].mSize * mArraySizes[ct]; 425 } 426 } 427 428 Element(int id, RenderScript rs, DataType dt, DataKind dk, boolean norm, int size) { 429 super(id, rs); 430 mSize = dt.mSize * size; 431 mType = dt; 432 mKind = dk; 433 mNormalized = norm; 434 mVectorSize = size; 435 } 436 437 Element(int id, RenderScript rs) { 438 super(id, rs); 439 } 440 441 @Override 442 void updateFromNative() { 443 super.updateFromNative(); 444 445 // we will pack mType; mKind; mNormalized; mVectorSize; NumSubElements 446 int[] dataBuffer = new int[5]; 447 mRS.nElementGetNativeData(getID(), dataBuffer); 448 449 mNormalized = dataBuffer[2] == 1 ? true : false; 450 mVectorSize = dataBuffer[3]; 451 mSize = 0; 452 for (DataType dt: DataType.values()) { 453 if(dt.mID == dataBuffer[0]){ 454 mType = dt; 455 mSize = mType.mSize * mVectorSize; 456 } 457 } 458 for (DataKind dk: DataKind.values()) { 459 if(dk.mID == dataBuffer[1]){ 460 mKind = dk; 461 } 462 } 463 464 int numSubElements = dataBuffer[4]; 465 if(numSubElements > 0) { 466 mElements = new Element[numSubElements]; 467 mElementNames = new String[numSubElements]; 468 469 int[] subElementIds = new int[numSubElements]; 470 mRS.nElementGetSubElements(getID(), subElementIds, mElementNames); 471 for(int i = 0; i < numSubElements; i ++) { 472 mElements[i] = new Element(subElementIds[i], mRS); 473 mElements[i].updateFromNative(); 474 mSize += mElements[i].mSize; 475 } 476 } 477 478 } 479 480 /** 481 * Create a custom Element of the specified DataType. The DataKind will be 482 * set to USER and the vector size to 1 indicating non-vector. 483 * 484 * @param rs The context associated with the new Element. 485 * @param dt The DataType for the new element. 486 * @return Element 487 */ 488 static Element createUser(RenderScript rs, DataType dt) { 489 DataKind dk = DataKind.USER; 490 boolean norm = false; 491 int vecSize = 1; 492 int id = rs.nElementCreate(dt.mID, dk.mID, norm, vecSize); 493 return new Element(id, rs, dt, dk, norm, vecSize); 494 } 495 496 /** 497 * Create a custom vector element of the specified DataType and vector size. 498 * DataKind will be set to USER. 499 * 500 * @param rs The context associated with the new Element. 501 * @param dt The DataType for the new element. 502 * @param size Vector size for the new Element. Range 2-4 inclusive 503 * supported. 504 * 505 * @return Element 506 */ 507 public static Element createVector(RenderScript rs, DataType dt, int size) { 508 if (size < 2 || size > 4) { 509 throw new RSIllegalArgumentException("Vector size out of range 2-4."); 510 } 511 DataKind dk = DataKind.USER; 512 boolean norm = false; 513 int id = rs.nElementCreate(dt.mID, dk.mID, norm, size); 514 return new Element(id, rs, dt, dk, norm, size); 515 } 516 517 /** 518 * Create a new pixel Element type. A matching DataType and DataKind must 519 * be provided. The DataType and DataKind must contain the same number of 520 * components. Vector size will be set to 1. 521 * 522 * @param rs The context associated with the new Element. 523 * @param dt The DataType for the new element. 524 * @param dk The DataKind to specify the mapping of each component in the 525 * DataType. 526 * 527 * @return Element 528 */ 529 public static Element createPixel(RenderScript rs, DataType dt, DataKind dk) { 530 if (!(dk == DataKind.PIXEL_L || 531 dk == DataKind.PIXEL_A || 532 dk == DataKind.PIXEL_LA || 533 dk == DataKind.PIXEL_RGB || 534 dk == DataKind.PIXEL_RGBA)) { 535 throw new RSIllegalArgumentException("Unsupported DataKind"); 536 } 537 if (!(dt == DataType.UNSIGNED_8 || 538 dt == DataType.UNSIGNED_5_6_5 || 539 dt == DataType.UNSIGNED_4_4_4_4 || 540 dt == DataType.UNSIGNED_5_5_5_1)) { 541 throw new RSIllegalArgumentException("Unsupported DataType"); 542 } 543 if (dt == DataType.UNSIGNED_5_6_5 && dk != DataKind.PIXEL_RGB) { 544 throw new RSIllegalArgumentException("Bad kind and type combo"); 545 } 546 if (dt == DataType.UNSIGNED_5_5_5_1 && dk != DataKind.PIXEL_RGBA) { 547 throw new RSIllegalArgumentException("Bad kind and type combo"); 548 } 549 if (dt == DataType.UNSIGNED_4_4_4_4 && dk != DataKind.PIXEL_RGBA) { 550 throw new RSIllegalArgumentException("Bad kind and type combo"); 551 } 552 553 int size = 1; 554 if (dk == DataKind.PIXEL_LA) { 555 size = 2; 556 } 557 if (dk == DataKind.PIXEL_RGB) { 558 size = 3; 559 } 560 if (dk == DataKind.PIXEL_RGBA) { 561 size = 4; 562 } 563 564 boolean norm = true; 565 int id = rs.nElementCreate(dt.mID, dk.mID, norm, size); 566 return new Element(id, rs, dt, dk, norm, size); 567 } 568 569 /** 570 * Builder class for producing complex elements with matching field and name 571 * pairs. The builder starts empty. The order in which elements are added 572 * is retained for the layout in memory. 573 * 574 */ 575 public static class Builder { 576 RenderScript mRS; 577 Element[] mElements; 578 String[] mElementNames; 579 int[] mArraySizes; 580 int mCount; 581 582 /** 583 * Create a builder object. 584 * 585 * @param rs 586 */ 587 public Builder(RenderScript rs) { 588 mRS = rs; 589 mCount = 0; 590 mElements = new Element[8]; 591 mElementNames = new String[8]; 592 mArraySizes = new int[8]; 593 } 594 595 /** 596 * Add an array of elements to this element. 597 * 598 * @param element 599 * @param name 600 * @param arraySize 601 */ 602 public Builder add(Element element, String name, int arraySize) { 603 if (arraySize < 1) { 604 throw new RSIllegalArgumentException("Array size cannot be less than 1."); 605 } 606 if(mCount == mElements.length) { 607 Element[] e = new Element[mCount + 8]; 608 String[] s = new String[mCount + 8]; 609 int[] as = new int[mCount + 8]; 610 System.arraycopy(mElements, 0, e, 0, mCount); 611 System.arraycopy(mElementNames, 0, s, 0, mCount); 612 System.arraycopy(mArraySizes, 0, as, 0, mCount); 613 mElements = e; 614 mElementNames = s; 615 mArraySizes = as; 616 } 617 mElements[mCount] = element; 618 mElementNames[mCount] = name; 619 mArraySizes[mCount] = arraySize; 620 mCount++; 621 return this; 622 } 623 624 /** 625 * Add a single element to this Element. 626 * 627 * @param element 628 * @param name 629 */ 630 public Builder add(Element element, String name) { 631 return add(element, name, 1); 632 } 633 634 /** 635 * Create the element from this builder. 636 * 637 * 638 * @return Element 639 */ 640 public Element create() { 641 mRS.validate(); 642 Element[] ein = new Element[mCount]; 643 String[] sin = new String[mCount]; 644 int[] asin = new int[mCount]; 645 java.lang.System.arraycopy(mElements, 0, ein, 0, mCount); 646 java.lang.System.arraycopy(mElementNames, 0, sin, 0, mCount); 647 java.lang.System.arraycopy(mArraySizes, 0, asin, 0, mCount); 648 649 int[] ids = new int[ein.length]; 650 for (int ct = 0; ct < ein.length; ct++ ) { 651 ids[ct] = ein[ct].getID(); 652 } 653 int id = mRS.nElementCreate2(ids, sin, asin); 654 return new Element(id, mRS, ein, sin, asin); 655 } 656 } 657} 658 659