CarouselView.java revision 51dd0196e4f3bd4086545f5bf30038ca9ad9ac27
1/* 2 * Copyright (C) 2010 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 com.android.ex.carousel; 18 19import android.view.View; 20import com.android.ex.carousel.CarouselRS.CarouselCallback; 21 22import android.content.Context; 23import android.graphics.Bitmap; 24import android.renderscript.Float4; 25import android.renderscript.Mesh; 26import android.renderscript.RSSurfaceView; 27import android.renderscript.RenderScriptGL; 28import android.util.AttributeSet; 29import android.view.MotionEvent; 30import android.view.SurfaceHolder; 31 32/** 33 * <p> 34 * This class represents the basic building block for using a 3D Carousel. The Carousel is 35 * basically a scene of cards and slots. The spacing between cards is dictated by the number 36 * of slots and the radius. The number of visible cards dictates how far the Carousel can be moved. 37 * If the number of cards exceeds the number of slots, then the Carousel will continue to go 38 * around until the last card can be seen. 39 */ 40public abstract class CarouselView extends RSSurfaceView { 41 private static final boolean USE_DEPTH_BUFFER = true; 42 private static final String TAG = "CarouselView"; 43 private CarouselRS mRenderScript; 44 private RenderScriptGL mRS; 45 private Context mContext; 46 private boolean mTracking; 47 48 CarouselController mController; 49 50 // Drag relative to x coordinate of motion on screen 51 public static final int DRAG_MODEL_SCREEN_DELTA = CarouselRS.DRAG_MODEL_SCREEN_DELTA; 52 // Drag relative to projected point on plane of carousel 53 public static final int DRAG_MODEL_PLANE = CarouselRS.DRAG_MODEL_PLANE; 54 // Drag relative to projected point on inside (far point) of cylinder centered around carousel 55 public static final int DRAG_MODEL_CYLINDER_INSIDE = CarouselRS.DRAG_MODEL_CYLINDER_INSIDE; 56 // Drag relative to projected point on outside (near point) of cylinder centered around carousel 57 public static final int DRAG_MODEL_CYLINDER_OUTSIDE = CarouselRS.DRAG_MODEL_CYLINDER_OUTSIDE; 58 59 // Draw cards counterclockwise around the carousel 60 public static final int FILL_DIRECTION_CCW = CarouselRS.FILL_DIRECTION_CCW; 61 // Draw cards clockwise around the carousel 62 public static final int FILL_DIRECTION_CW = CarouselRS.FILL_DIRECTION_CW; 63 64 // Note: remember to update carousel.rs when changing the values below 65 public static class DetailAlignment { 66 /** Detail is centered vertically with respect to the card **/ 67 public static final int CENTER_VERTICAL = 1; 68 /** Detail is aligned with the top edge of the carousel view **/ 69 public static final int VIEW_TOP = 1 << 1; 70 /** Detail is aligned with the bottom edge of the carousel view (not yet implemented) **/ 71 public static final int VIEW_BOTTOM = 1 << 2; 72 /** Detail is positioned above the card (not yet implemented) **/ 73 public static final int ABOVE = 1 << 3; 74 /** Detail is positioned below the card **/ 75 public static final int BELOW = 1 << 4; 76 /** Mask that selects those bits that control vertical alignment **/ 77 public static final int VERTICAL_ALIGNMENT_MASK = 0xff; 78 79 /** 80 * Detail is centered horizontally with respect to either the top or bottom 81 * extent of the card, depending on whether the detail is above or below the card. 82 */ 83 public static final int CENTER_HORIZONTAL = 1 << 8; 84 /** 85 * Detail is aligned with the left edge of either the top or the bottom of 86 * the card, depending on whether the detail is above or below the card. 87 */ 88 public static final int LEFT = 1 << 9; 89 /** 90 * Detail is aligned with the right edge of either the top or the bottom of 91 * the card, depending on whether the detail is above or below the card. 92 * (not yet implemented) 93 */ 94 public static final int RIGHT = 1 << 10; 95 /** Mask that selects those bits that control horizontal alignment **/ 96 public static final int HORIZONTAL_ALIGNMENT_MASK = 0xff00; 97 } 98 99 public static class Info { 100 public Info(int _resId) { resId = _resId; } 101 public int resId; // resource for renderscript resource (e.g. R.raw.carousel) 102 } 103 104 public abstract Info getRenderScriptInfo(); 105 106 public CarouselView(Context context) { 107 this(context, new CarouselController()); 108 } 109 110 public CarouselView(Context context, CarouselController controller) { 111 this(context, null, controller); 112 } 113 114 /** 115 * Constructor used when this widget is created from a layout file. 116 */ 117 public CarouselView(Context context, AttributeSet attrs) { 118 this(context, attrs, new CarouselController()); 119 } 120 121 public CarouselView(Context context, AttributeSet attrs, CarouselController controller) { 122 super(context, attrs); 123 mContext = context; 124 mController = controller; 125 boolean useDepthBuffer = true; 126 ensureRenderScript(); 127 // TODO: add parameters to layout 128 129 setOnLongClickListener(new View.OnLongClickListener() { 130 public boolean onLongClick(View v) { 131 if (interpretLongPressEvents()) { 132 mController.onLongPress(); 133 return true; 134 } else { 135 return false; 136 } 137 } 138 }); 139 } 140 141 private void ensureRenderScript() { 142 if (mRS == null) { 143 RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig(); 144 if (USE_DEPTH_BUFFER) { 145 sc.setDepth(16, 24); 146 } 147 mRS = createRenderScript(sc); 148 } 149 if (mRenderScript == null) { 150 mRenderScript = new CarouselRS(mRS, mContext.getResources(), 151 getRenderScriptInfo().resId); 152 mRenderScript.resumeRendering(); 153 } 154 mController.setRS(mRS, mRenderScript); 155 } 156 157 @Override 158 public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) { 159 super.surfaceChanged(holder, format, w, h); 160 // setZOrderOnTop(true); 161 mController.onSurfaceChanged(); 162 } 163 164 public CarouselController getController() { 165 return mController; 166 } 167 168 public void setController(CarouselController controller) { 169 mController = controller; 170 mController.setRS(mRS, mRenderScript); 171 } 172 173 /** 174 * Do I want to interpret the long-press gesture? If so, long-presses will cancel the 175 * current selection and call the appropriate callbacks. Otherwise, a long press will 176 * not be handled any way other than as a continued drag. 177 * 178 * @return True if we interpret long-presses 179 */ 180 public boolean interpretLongPressEvents() { 181 return false; 182 } 183 184 /** 185 * Loads geometry from a resource id. 186 * 187 * @param resId 188 * @return the loaded mesh or null if it cannot be loaded 189 */ 190 public Mesh loadGeometry(int resId) { 191 return mController.loadGeometry(mContext.getResources(), resId); 192 } 193 194 /** 195 * Load A3D file from resource. If resId == 0, will clear geometry for this item. 196 * @param n 197 * @param resId 198 */ 199 public void setGeometryForItem(int n, Mesh mesh) { 200 mController.setGeometryForItem(n, mesh); 201 } 202 203 /** 204 * Set the number of slots around the Carousel. Basically equivalent to the poles horses 205 * might attach to on a real Carousel. 206 * 207 * @param n the number of slots 208 */ 209 public void setSlotCount(int n) { 210 mController.setSlotCount(n); 211 } 212 213 /** 214 * Sets the number of visible slots around the Carousel. This is primarily used as a cheap 215 * form of clipping. The Carousel will never show more than this many cards. 216 * @param n the number of visible slots 217 */ 218 public void setVisibleSlots(int n) { 219 mController.setVisibleSlots(n); 220 } 221 222 /** 223 * Set the number of cards to pre-load that are outside of the visible region, as determined by 224 * setVisibleSlots(). This number gets added to the number of visible slots and used to 225 * determine when resources for cards should be loaded. This number should be small (n <= 4) 226 * for systems with limited texture memory or views that show more than half dozen cards in the 227 * view. 228 * 229 * @param n the number of cards; should be even, so the count is the same on each side 230 */ 231 public void setPrefetchCardCount(int n) { 232 mController.setPrefetchCardCount(n); 233 } 234 235 /** 236 * Sets the number of rows of cards to show in each slot. 237 */ 238 public void setRowCount(int n) { 239 mController.setRowCount(n); 240 } 241 242 /** 243 * Sets the spacing between each row of cards when rowCount > 1. 244 */ 245 public void setRowSpacing(float s) { 246 mController.setRowSpacing(s); 247 } 248 249 /** 250 * Set the number of detail textures that can be visible at one time. 251 * 252 * @param n the number of slots 253 */ 254 public void setVisibleDetails(int n) { 255 mController.setVisibleDetails(n); 256 } 257 258 /** 259 * Sets how detail textures are aligned with respect to the card. 260 * 261 * @param alignment a bitmask of DetailAlignment flags. 262 */ 263 public void setDetailTextureAlignment(int alignment) { 264 mController.setDetailTextureAlignment(alignment); 265 } 266 267 /** 268 * Set whether depth is enabled while blending. Generally, this is discouraged because 269 * it causes bad artifacts. Careful attention to geometry and alpha transparency of 270 * textures can mitigate much of this. For example, geometry for an item must be drawn 271 * back-to-front if any edges overlap. 272 * 273 * @param enabled True to enable depth while blending, and false to disable it. 274 */ 275 public void setForceBlendCardsWithZ(boolean enabled) { 276 mController.setForceBlendCardsWithZ(enabled); 277 } 278 279 /** 280 * Set whether to draw a ruler from the card to the detail texture 281 * 282 * @param drawRuler True to draw a ruler, false to draw nothing where the ruler would go. 283 */ 284 public void setDrawRuler(boolean drawRuler) { 285 mController.setDrawRuler(drawRuler); 286 } 287 288 /** 289 * This dictates how many cards are in the deck. If the number of cards is greater than the 290 * number of slots, then the Carousel goes around n / slot_count times. 291 * 292 * Can be called again to increase or decrease the number of cards. 293 * 294 * @param n the number of cards to create. 295 */ 296 public void createCards(int n) { 297 mController.createCards(n); 298 } 299 300 public int getCardCount() { 301 return mController.getCardCount(); 302 } 303 304 /** 305 * This sets the texture on card n. It should only be called in response to 306 * {@link CarouselCallback#onRequestTexture(int)}. Since there's no guarantee 307 * that a given texture is still on the screen, replacing this texture should be done 308 * by first setting it to null and then waiting for the next 309 * {@link CarouselCallback#onRequestTexture(int)} to swap it with the new one. 310 * 311 * @param n the card given by {@link CarouselCallback#onRequestTexture(int)} 312 * @param bitmap the bitmap image to show 313 */ 314 public void setTextureForItem(int n, Bitmap bitmap) { 315 mController.setTextureForItem(n, bitmap); 316 } 317 318 /** 319 * This sets the detail texture that floats above card n. It should only be called in response 320 * to {@link CarouselCallback#onRequestDetailTexture(int)}. Since there's no guarantee 321 * that a given texture is still on the screen, replacing this texture should be done 322 * by first setting it to null and then waiting for the next 323 * {@link CarouselCallback#onRequestDetailTexture(int)} to swap it with the new one. 324 * 325 * @param n the card to set detail texture for 326 * @param offx an optional offset to apply to the texture (in pixels) from top of detail line 327 * @param offy an optional offset to apply to the texture (in pixels) from top of detail line 328 * @param loffx an optional offset to apply to the line (in pixels) from left edge of card 329 * @param loffy an optional offset to apply to the line (in pixels) from top of screen 330 * @param bitmap the bitmap to show as the detail 331 */ 332 public void setDetailTextureForItem(int n, float offx, float offy, float loffx, float loffy, 333 Bitmap bitmap) { 334 mController.setDetailTextureForItem(n, offx, offy, loffx, loffy, bitmap); 335 } 336 337 /** 338 * Sets the bitmap to show on a card when the card draws the very first time. 339 * Generally, this bitmap will only be seen during the first few frames of startup 340 * or when the number of cards are changed. It can be ignored in most cases, 341 * as the cards will generally only be in the loading or loaded state. 342 * 343 * @param bitmap 344 */ 345 public void setDefaultBitmap(Bitmap bitmap) { 346 mController.setDefaultBitmap(bitmap); 347 } 348 349 /** 350 * Sets the bitmap to show on the card while the texture is loading. It is set to this 351 * value just before {@link CarouselCallback#onRequestTexture(int)} is called and changed 352 * when {@link CarouselView#setTextureForItem(int, Bitmap)} is called. It is shared by all 353 * cards. 354 * 355 * @param bitmap 356 */ 357 public void setLoadingBitmap(Bitmap bitmap) { 358 mController.setLoadingBitmap(bitmap); 359 } 360 361 /** 362 * Sets background to specified color. If a background texture is specified with 363 * {@link CarouselView#setBackgroundBitmap(Bitmap)}, then this call has no effect. 364 * 365 * @param red the amount of red 366 * @param green the amount of green 367 * @param blue the amount of blue 368 * @param alpha the amount of alpha 369 */ 370 public void setBackgroundColor(float red, float green, float blue, float alpha) { 371 mController.setBackgroundColor(red, green, blue, alpha); 372 } 373 374 /** 375 * Can be used to optionally set the background to a bitmap. When set to something other than 376 * null, this overrides {@link CarouselView#setBackgroundColor(Float4)}. 377 * 378 * @param bitmap 379 */ 380 public void setBackgroundBitmap(Bitmap bitmap) { 381 mController.setBackgroundBitmap(bitmap); 382 } 383 384 /** 385 * Can be used to optionally set a "loading" detail bitmap. Typically, this is just a black 386 * texture with alpha = 0 to allow details to slowly fade in. 387 * 388 * @param bitmap 389 */ 390 public void setDetailLoadingBitmap(Bitmap bitmap) { 391 mController.setDetailLoadingBitmap(bitmap); 392 } 393 394 /** 395 * This texture is used to draw a line from the card alongside the texture detail. The line 396 * will be as wide as the texture. It can be used to give the line glow effects as well as 397 * allowing other blending effects. It is typically one dimensional, e.g. 3x1. 398 * 399 * @param bitmap 400 */ 401 public void setDetailLineBitmap(Bitmap bitmap) { 402 mController.setDetailLineBitmap(bitmap); 403 } 404 405 /** 406 * This geometry will be shown when no geometry has been loaded for a given slot. If not set, 407 * a quad will be drawn in its place. It is shared for all cards. If something other than 408 * simple planar geometry is used, consider enabling depth test with 409 * {@link CarouselView#setForceBlendCardsWithZ(boolean)} 410 * 411 * @param mesh 412 */ 413 public void setDefaultGeometry(Mesh mesh) { 414 mController.setDefaultGeometry(mesh); 415 } 416 417 /** 418 * Sets the matrix used to transform card geometries. By default, this 419 * is the identity matrix, but you can specify a different matrix if you 420 * want to scale, translate and / or rotate the card before drawing. 421 * 422 * @param matrix array of 9 or 16 floats representing a 3x3 or 4x4 matrix, 423 * or null as a shortcut for an identity matrix. 424 */ 425 public void setDefaultCardMatrix(float[] matrix) { 426 mController.setDefaultCardMatrix(matrix); 427 } 428 429 /** 430 * This is an intermediate version of the object to show while geometry is loading. If not set, 431 * a quad will be drawn in its place. It is shared for all cards. If something other than 432 * simple planar geometry is used, consider enabling depth test with 433 * {@link CarouselView#setForceBlendCardsWithZ(boolean)} 434 * 435 * @param mesh 436 */ 437 public void setLoadingGeometry(Mesh mesh) { 438 mController.setLoadingGeometry(mesh); 439 } 440 441 /** 442 * Sets the callback for receiving events from RenderScript. 443 * 444 * @param callback 445 */ 446 public void setCallback(CarouselCallback callback) 447 { 448 mController.setCallback(callback); 449 } 450 451 /** 452 * Sets the startAngle for the Carousel. The start angle is the first position of the first 453 * slot draw. Cards will be drawn from this angle in a counter-clockwise manner around the 454 * Carousel. 455 * 456 * @param angle the angle, in radians. 457 */ 458 public void setStartAngle(float angle) 459 { 460 mController.setStartAngle(angle); 461 } 462 463 public void setRadius(float radius) { 464 mController.setRadius(radius); 465 } 466 467 public void setCardRotation(float cardRotation) { 468 mController.setCardRotation(cardRotation); 469 } 470 471 public void setCardsFaceTangent(boolean faceTangent) { 472 mController.setCardsFaceTangent(faceTangent); 473 } 474 475 public void setSwaySensitivity(float swaySensitivity) { 476 mController.setSwaySensitivity(swaySensitivity); 477 } 478 479 public void setFrictionCoefficient(float frictionCoefficient) { 480 mController.setFrictionCoefficient(frictionCoefficient); 481 } 482 483 public void setDragFactor(float dragFactor) { 484 mController.setDragFactor(dragFactor); 485 } 486 487 public void setDragModel(int model) { 488 mController.setDragModel(model); 489 } 490 491 public void setLookAt(float[] eye, float[] at, float[] up) { 492 mController.setLookAt(eye, at, up); 493 } 494 495 /** 496 * This sets the number of cards in the distance that will be shown "rezzing in". 497 * These alpha values will be faded in from the background to the foreground over 498 * 'n' cards. A floating point value is used to allow subtly changing the rezzing in 499 * position. 500 * 501 * @param n the number of cards to rez in. 502 */ 503 public void setRezInCardCount(float n) { 504 mController.setRezInCardCount(n); 505 } 506 507 /** 508 * This sets the duration (in ms) that a card takes to fade in when loaded via a call 509 * to {@link CarouselView#setTextureForItem(int, Bitmap)}. The timer starts the 510 * moment {@link CarouselView#setTextureForItem(int, Bitmap)} is called and continues 511 * until all of the cards have faded in. Note: using large values will extend the 512 * animation until all cards have faded in. 513 * 514 * @param t 515 */ 516 public void setFadeInDuration(long t) { 517 mController.setFadeInDuration(t); 518 } 519 520 @Override 521 protected void onDetachedFromWindow() { 522 super.onDetachedFromWindow(); 523 mRenderScript = null; 524 if (mRS != null) { 525 mRS = null; 526 destroyRenderScript(); 527 } 528 mController.setRS(mRS, mRenderScript); 529 } 530 531 @Override 532 protected void onAttachedToWindow() { 533 super.onAttachedToWindow(); 534 ensureRenderScript(); 535 } 536 537 @Override 538 public boolean onTouchEvent(MotionEvent event) { 539 super.onTouchEvent(event); 540 final int action = event.getAction(); 541 542 if (mRenderScript == null) { 543 return true; 544 } 545 546 switch (action) { 547 case MotionEvent.ACTION_DOWN: 548 mTracking = true; 549 mController.onTouchStarted(event.getX(), event.getY(), event.getEventTime()); 550 break; 551 552 case MotionEvent.ACTION_MOVE: 553 if (mTracking) { 554 for (int i = 0; i < event.getHistorySize(); i++) { 555 mController.onTouchMoved(event.getHistoricalX(i), event.getHistoricalY(i), 556 event.getHistoricalEventTime(i)); 557 } 558 mController.onTouchMoved(event.getX(), event.getY(), event.getEventTime()); 559 } 560 break; 561 562 case MotionEvent.ACTION_UP: 563 mController.onTouchStopped(event.getX(), event.getY(), event.getEventTime()); 564 mTracking = false; 565 break; 566 } 567 568 return true; 569 } 570} 571