Mobile 3d Graphics Api For Java 2 Micro Edition

Version 10 download

https://ebookbell.com/product/mobile-3d-graphics-api-for-
java-2-micro-edition-version-10-4092608

Explore and download more ebooks at ebookbell.com

Here are some recommended products that we believe you will be
interested in. You can click the link to download.

Mobile 3d Graphics Learning 3d Graphics With The Java Micro Edition

Claus Hofele

https://ebookbell.com/product/mobile-3d-graphics-learning-3d-graphics-
with-the-java-micro-edition-claus-hofele-4124812

Mobile 3d Graphics 1st Edition Alessio Malizia Auth

https://ebookbell.com/product/mobile-3d-graphics-1st-edition-alessio-
malizia-auth-4191144

Mobile 3d Graphics With Opengl Es And M3g Kari Pulli Tomi Aarnio

https://ebookbell.com/product/mobile-3d-graphics-with-opengl-es-
and-m3g-kari-pulli-tomi-aarnio-1273348

Mobile 3d Graphics Soc From Algorithm To Chip Hoijun Yoo Jeongho Woo

https://ebookbell.com/product/mobile-3d-graphics-soc-from-algorithm-
to-chip-hoijun-yoo-jeongho-woo-1565852
Tracking Objects In 3d Using Stereo Visiona Realtime Approach Based On
Color Segmentation For Use On A Mobile Robot 2010th Edition Kai Hugo
Hustoft Endresen

https://ebookbell.com/product/tracking-objects-in-3d-using-stereo-
visiona-realtime-approach-based-on-color-segmentation-for-use-on-a-
mobile-robot-2010th-edition-kai-hugo-hustoft-endresen-72557720

Flash Game Development In A Social Mobile And 3d World Glen Rhodes

https://ebookbell.com/product/flash-game-development-in-a-social-
mobile-and-3d-world-glen-rhodes-37442322

Mobile Narratives Travel Migration And Transculturation Eleftheria

Arapoglou Editor

https://ebookbell.com/product/mobile-narratives-travel-migration-and-
transculturation-eleftheria-arapoglou-editor-44875674

Mobile Robotics Mathematics Models And Methods Instructor Solution

Manual Solutions 1st Edition Alonzo Kelly

https://ebookbell.com/product/mobile-robotics-mathematics-models-and-
methods-instructor-solution-manual-solutions-1st-edition-alonzo-
kelly-46072166

Mobile Cloud Computing Foundations And Service Models Huijun Wu

Dijiang Huang

https://ebookbell.com/product/mobile-cloud-computing-foundations-and-
service-models-huijun-wu-dijiang-huang-46500634
 Mobile 3D Graphics API
for Java™2 Micro Edition

Version 1.0, November 19, 2003

JSR-184 Expert Group, [email protected]

Java Community Process (JCP)

Copyright Notice and Disclaimers
JSR-184 Mobile 3D Graphics API for J2ME Specification ("Specification")
Version: 1.0
Status: Final Release
Specification Lead: Nokia Corporation ("Specification Lead")
Release: 2003-11-19
Copyright 2003 Nokia Corporation.
All rights reserved.
NOTICE; LIMITED LICENSE GRANTS
Specification Lead hereby grants You a fully-paid, non-exclusive, non-transferable, worldwide,
limited license (without the right to sublicense), under the Specification Lead's applicable intel-
lectual property rights to view, download, use and reproduce the Specification only for the pur-
pose of internal evaluation, which shall be understood to include developing applications intended
to run on an implementation of the Specification provided that such applications do not them-
selves implement any portion(s) of the Specification. The Specification contains proprietary
information of the Specification Lead and may only be used in accordance with the license terms
set forth herein.
Subject to the reciprocity requirement set forth below Specification Lead also grants You a per-
petual, non-exclusive, worldwide, fully paid-up, royalty free, irrevocable limited license (without
the right to sublicense) under any applicable copyrights or patent rights it may have in the Speci-
fication to create and/or distribute an Independent Implementation of the Specification that: (a)
fully implements the Specification without modifying, subsetting or extending the public class or
interface declarations whose names begin with "java" or "javax" or their equivalents in any subse-
quent naming convention adopted by Specification Lead through the Java Community Process, or
any recognized successors or replacements thereof; (b) implement all required interfaces and
functionality of the Specification; (c) only include as part of such Independent Implementation
the packages, classes or methods specified by the Specification; (d) pass the technology compati-
bility kit ("TCK") for such Specification; and (e) are designed to operate on a Java platform which
is certified to pass the complete TCK for such Java platform. For the purpose of this agreement
the applicable patent rights shall mean any claims for which there is no technically feasible way
of avoiding infringement in the course of implementing the Specification. Other than this limited
license, You acquire no right, license, title or interest in or to the Specification or any other intel-
lectual property rights of the Specification Lead.
You need not include limitations (a)-(e) from the previous paragraph or any other particular "pass
through" requirements in any license You grant concerning the use of Your Independent Imple-
mentation or products derived from it. However, except with respect to implementations of the
Specification (and products derived from them) by Your licensee that satisfy limitations (a)-(e)
from the previous paragraph, You may neither: (i) grant or otherwise pass through to Your licens-
ees any licenses under Specification Lead's applicable intellectual property rights; nor (ii) autho-
rize Your licensees to make any claims concerning their implementation's compliance with the
Specification in question.
The license provisions concerning the grant of licenses hereunder shall be subject to reciprocity
requirement so that Specification Lead's grant of licenses shall not be effective as to You if, with
respect to the Specification licensed hereunder, You (on behalf of yourself and any party for
which You are authorized to act with respect to this Agreement) do not make available, in fact and
practice, to Specification Lead and to other licensees of Specification on fair, reasonable and non-
discriminatory terms a perpetual, irrevocable, non-exclusive, non-transferable, worldwide license
under such Your (and such party's for which You are authorized to act with respect to this Agree-
ment) patent rights which are or would be infringed by all technically feasible implementations of
the Specification to develop, distribute and use an Independent Implementation of the Specifica-
tion within the scope of the licenses granted above by Specification Lead. However, You shall not
be required to grant a license:
1. to a licensee not willing to grant a reciprocal license under its patent rights to You and to any
other party seeking such a license with respect to the enforcement of such licensee's patent claims
where there is no technically feasible alternative that would avoid the infringement of such
claims;
2. with respect to any portion of any product and any combinations thereof the sole purpose or
function of which is not required in order to be fully compliant with the Specification; or
3. with respect to technology that is not required for developing, distributing and using an Inde-
pendent Implementation.
Furthermore, You hereby grant a non-exclusive, worldwide, royalty-free, perpetual and irrevoca-
ble covenant to Specification Lead that You shall not bring a suit before any court or administra-
tive agency or otherwise assert a claim that the Specification Lead has, in the course of
performing its responsibilities as the Specification Lead under JCP process rules, induced any
other entity to infringe Your patent rights.
For the purposes of this Agreement: "Independent Implementation" shall mean an implementation
of the Specification that neither derives from the reference implementation to the Specification
("Reference Implementation") source code or binary code materials nor, except with an appropri-
ate and separate license from licensor of the Reference Implementation, includes any of Refer-
ence Implementation's source code or binary code materials.
This Agreement will terminate immediately without notice from Specification Lead if You fail to
comply with any material provision of or act outside the scope of the licenses granted above.
TRADEMARKS
Nokia is a registered trademark of Nokia Corporation. Nokia Corporation's product names are
either trademarks or registered trademarks of Nokia Corporation Your access to this Specification
should not be construed as granting, by implication, estoppel or otherwise, any license or right to
use any marks appearing in the Specification without the prior written consent of Nokia Corpora-
tion or Nokia's licensors.
No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun's
licensors, is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java, J2ME, and the Java
Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S.
and other countries.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS". SPECIFICATION LEAD MAKES NO REPRE-
SENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICU-
LAR PURPOSE, OR NON-INFRINGEMENT, THAT THE CONTENTS OF THE SPECIFICA-
TION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR
IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY
PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not
represent any commitment to release or implement any portion of the Specification in any prod-
uct.
THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPO-
GRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMA-
TION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS
OF THE SPECIFICATION, IF ANY. SPECIFICATION LEAD MAY MAKE IMPROVEMENTS
AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be
governed by the then-current license for the applicable version of the Specification.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SPECIFICATION
LEAD OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT
LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CON-
SEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO
ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION,
EVEN IF SPECIFICATION LEAD AND/OR ITS LICENSORS HAVE BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES.
You will indemnify, hold harmless, and defend Specification Lead and its licensors from any
claims arising or resulting from: (i) Your use of the Specification; (ii) the use or distribution of
Your Java application, applet and/or clean room implementation; and/or (iii) any claims that later
versions or releases of any Specification furnished to You are incompatible with the Specification
provided to You under this license.
RESTRICTED RIGHTS LEGEND
U.S. Government: If this Specification is being acquired by or on behalf of the U.S. Government
or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's
rights in the Software and accompanying documentation shall be only as set forth in this license;
this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense
(DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).
REPORT
You may wish to report any ambiguities, inconsistencies or inaccuracies You may find in connec-
tion with Your use of the Specification ("Feedback"). To the extent that You provide Specification
Lead with any Feedback, You hereby: (i) agree that such Feedback is provided on a non-propri-
etary and non-confidential basis, and (ii) grant Specification Lead a perpetual, non-exclusive,
worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels
of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose
related to the Specification and future versions, implementations, and test suites thereof.
Contents
Overview ......................................................................................................... 1
javax.microedition.m3g ................................................................................. 7
AnimationController ................................................................................................................................. 19
AnimationTrack ........................................................................................................................................ 26
Appearance ................................................................................................................................................ 34
Background ............................................................................................................................................... 40
Camera ...................................................................................................................................................... 46
CompositingMode ..................................................................................................................................... 52
Fog ............................................................................................................................................................ 59
Graphics3D ............................................................................................................................................... 63
Group ........................................................................................................................................................ 79
Image2D .................................................................................................................................................... 85
IndexBuffer ............................................................................................................................................... 91
KeyframeSequence ................................................................................................................................... 92
Light ........................................................................................................................................................ 101
Loader ..................................................................................................................................................... 108
Material ................................................................................................................................................... 113
Mesh ........................................................................................................................................................ 118
MorphingMesh ........................................................................................................................................ 123
Node ........................................................................................................................................................ 129
Object3D ................................................................................................................................................. 138
PolygonMode .......................................................................................................................................... 146
RayIntersection ....................................................................................................................................... 151
SkinnedMesh ........................................................................................................................................... 155
Sprite3D .................................................................................................................................................. 162
Texture2D ............................................................................................................................................... 169
Transform ................................................................................................................................................ 178
Transformable ......................................................................................................................................... 185
TriangleStripArray .................................................................................................................................. 191
VertexArray ............................................................................................................................................ 194
VertexBuffer ........................................................................................................................................... 197
World ...................................................................................................................................................... 204

Almanac ...................................................................................................... 211

Index ........................................................................................................... 223
File Format ........................................................................................ Appendix
Overview
Description
This specification defines the Mobile 3D Graphics API (M3G) for J2ME.

Preface
This document contains the specification of the Mobile 3D Graphics API (abbreviated “M3G”) for the Java 2
Platform, Micro Edition (“J2ME”). The specification was defined within the Java Community Process (“JCP”)
under Java Specification Request 184 (“JSR-184”). The specification is subject to the terms of the JCP
agreements (i.e. JSPA and/or IEPA).
The Mobile 3D Graphics API is an optional package. An optional package can be adopted to existing J2ME
profiles. A profile of J2ME defines device-type-specific sets of APIs for a particular vertical market or industry.
The main target platform of this optional API is J2ME/CLDC, used with profiles such as MIDP 1.0 or MIDP
2.0. However, the API can also be implemented on top of J2ME/CDC, or any Java platform in general.
Technical details of the API can be found in the package overview and the individual class descriptions; see
especially the Graphics3D class. To see how the API is used in practice, refer to the example MIDlets at the end
of the Package overview.
This specification uses definitions based upon those specified in RFC 2119 (available on the IETF web site
(http://www.ietf.org)).

Term Definition
MUST The associated definition is an absolute requirement of
this specification.
MUST NOT The definition is an absolute prohibition of this
specification.
SHOULD Indicates a recommended practice. There may exist
valid reasons in particular circumstances to ignore this
recommendation, but the full implications must be
understood and carefully weighed before choosing a
different course.
SHOULD NOT Indicates a non-recommended practice. There may
exist valid reasons in particular circumstances when
the particular behavior is acceptable or even useful,
but the full implications should be understood and the
case carefully weighed before implementing any
behavior described with this label.
MAY Indicates that an item is truly optional.

Background
The objective of the Mobile 3D Graphics API Expert Group was to provide an efficient 3D Graphics API
suitable for the J2ME platform, in particular CLDC/MIDP. The API is targeted at CLDC class of devices that
typically have very little processing power and memory, and no hardware support for 3D graphics or floating
point math. The API has been defined such that implementations on that kind of hardware are feasible.

1
Overview

However, the API also scales up to higher-end devices featuring a color display, a DSP, a floating point unit, or
even specialized 3D graphics hardware.
The M3G specification is based on the requirements, summarized below, that were agreed on by the Expert
Group. The rationale for each requirement is presented in the paragraphs following the summary.
• The API must support retained mode access (that is, a scene graph).
• The API must support immediate mode access, with features similar to OpenGL.
• The API must support mixing and matching of immediate and retained mode access.
• The API must not include optional parts (that is, all methods must be implemented).
• The API must have importers for meshes, textures, entire scene graphs, etc.
• The API must be efficiently implementable on top of OpenGL ES.
• The API must use the native float data type of Java, not introduce a custom type.
• The API must be efficiently implementable without floating point hardware.
• The API should be implementable within 150 kB on a real mobile terminal.
• The API must be structured so that garbage collection is minimized.
• The API must be interoperable with related Java APIs, especially with MIDP.
Several applications were identified for the Mobile 3D Graphics API, including games, map visualization, user
interfaces, animated messages, product visualization, and screen savers. Each of these have different needs:
some require simple content creation, some require high polygon throughput, yet others require high quality
still images with special effects.
It is clear that such a wide spectrum of different needs cannot be fulfilled by a scene graph API alone, nor an
immediate mode API alone. It is also clear that having two separate APIs would lead to developer confusion
and sub-optimal usage of precious memory space. Rather, there must be only one indivisible API, with only one
RI and TCK, that covers both types of access in a unified way. A developer should be able to use either one, or
both at the same time, depending on the task at hand.
The immediate mode (or low-level) part of the API should be a subset of OpenGL with no added functionality.
That is, the low-level features should be compatible with OpenGL ES, which is being standardized by Khronos.
For the Reference Implementation, the scene graph (or high-level) part must be built on top of the low-level
interface, and shall never bypass it when rendering. This ensures that the scene graph does not include rendering
features that cannot be implemented directly with the low-level interface. The low-level implementation may
then be changed freely, or even accelerated with dedicated hardware.
In many cases, there is little else to an application than displaying a scene and playing back some animation
created in a 3D modeling tool. This should not require much Java programming. Even in more demanding
cases, it greatly speeds up development if it is easy to import objects and animations into a midlet. Therefore,
the API must provide importer functions for different data types, such as textures, meshes, animations, and
scene hierarchies. The data must be encoded in a binary format for compact storage and transmission.
Most mobile terminals do not have hardware support for floating point processing. This should be reflected in
the API, so that it can be efficiently implemented using integer arithmetic. However, since programming with
fixed point mathematics is difficult and error prone, the API should use floating point values wherever feasible,
and plain integers otherwise. Fixed point values must not be used. Also, instead of introducing a custom Float
type or packing floating point values into integers, Java’s built-in float data type must be used. As a
consequence, this API can not be implemented on top of CLDC 1.0.
Like all APIs targeting MIDP, we need to strive for as compact an implementation as possible. It should be
possible to implement the API in less than 150 kB of ROM space, including the native graphics engine, Java

2
 Overview

class files (ROMized), and content importing facilities. To minimize garbage collection, the API should be
structured so that using it does not require repetitive creation of objects.
The API must be tightly integrated with MIDP’s LCDUI, such that 2D and 3D graphics can be efficiently
rendered on the same Canvas or Image, for example. The decision of whether to use double buffering or not
should be delegated to the MIDP implementation. The API should also be able to bind with other GUI APIs,
such as AWT.

Related Literature
• The Java Language Specification, James Gosling, Bill Joy, and Guy L. Steele, 1996.
• Quaternion Algebra and Calculus (http://www.magic-software.com/Documentation/Quaternions.pdf),
David Eberly, 1999.
• Key Frame Interpolation via Splines and Quaternions (http://www.magic-software.com/Documentation/
KeyframeAnimation.pdf), David Eberly, 1999.
• Connected, Limited Device Configuration (JSR-30) (http://java.sun.com/products/cldc/), Sun
Microsystems, Inc.
• Connected, Limited Device Configuration 1.1 (JSR-139) (http://jcp.org/en/jsr/detail?id=139), Sun
Microsystems, Inc.
• Connected Device Configuration (JSR-36) (http://java.sun.com/products/cdc/), Sun Microsystems, Inc.
• Mobile Information Device Profile (JSR-37) (http://java.sun.com/products/midp/), Sun Microsystems, Inc.
• Mobile Information Device Profile 2.0 (JSR-118) (http://jcp.org/jsr/detail/118.jsp), Sun Microsystems, Inc.
• OpenGL 1.3 Specification (http://www.opengl.org/developers/documentation/version1_3/glspec13.pdf),
Silicon Graphics, Inc.
• PNG file format (http://www.w3.org/TR/PNG), World Wide Web Consortium (W3C).

Expert Group
The Mobile 3D Graphics API (JSR-184) Expert Group consisted of the following companies and individuals:
Nokia (Specification Lead)
Aplix Corporation
ARM
Bandai Networks
Cingular Wireless
Cellon France
France Telecom
Fuetrek
HI Corporation
Hybrid Graphics
In-Fusio
Insignia Solutions
Intel
Intergrafx
MathEngine
Motorola
Research In Motion
Siemens
Sony Ericsson Mobile Communications
Sun Microsystems, Inc.

3
Overview

Superscape
Symbian
Texas Instruments Inc.
3d4W
Vodafone
Zucotto Wireless
Fredrik Kekalainen (Fathammer)
Mika Tammenkoski (Sumea)

Revision History

Date Version Description

11-Sept-2002 EG Draft 1 Based on the 2nd Expert Group meeting
20-Sept-2002 EG Draft 2
31-Oct-2002 EG Draft 3 For review in the 3rd EG meeting
15-Nov-2002 EG Draft 4 Based on the 3rd EG meeting
29-Nov-2002 EG Draft 5
17-Dec-2002 EG Draft 6
16-Jan-2003 EG Draft 7 For review in the 4th EG meeting
31-Jan-2003 EG Draft 8 Updated as per EG meeting resolutions.
14-Feb-2003 EG Draft 9 First Community Review candidate.
19-Feb-2003 EG Draft 10 Community Review specification.
11-Apr-2003 EG Draft 11 Updated according to Community Review feedback.
30-Apr-2003 EG Draft 12 Public Review specification.
6-Jun-2003 EG Draft 13 Updated according to Public Review feedback.
9-Jul-2003 EG Draft 14 Proposed Final Draft Candidate.
11-Jul-2003 EG Draft 15 Proposed Final Draft.
12-Sep-2003 EG Draft 16 Proposed Final Draft 2.
26-Sep-2003 EG Draft 17 Proposed Final Draft 3.
15-Oct-2003 Final Draft Submitted to JCP PMO.
19-Nov-2003 Version 1.0 Final Release.

Package Summary
Other Packages

4
 Overview

Package Summary
javax.microedition.m3g Defines an API for rendering three-dimensional (3D) graphics at interactive frame
7 rates, including a scene graph structure and a corresponding file format for efficient
management and deployment of 3D content.

5
Overview

6
Package
javax.microedition.m3g
Description
Defines an API for rendering three-dimensional (3D) graphics at interactive frame rates, including a scene
graph structure and a corresponding file format for efficient management and deployment of 3D content.
The function of this API is to provide Java application programmers with an efficient and flexible means to
display animated 3D graphics in real time on embedded devices. To cater for the needs of different types of
applications, both an easy-to-use scene graph structure and an immediate mode interface are provided. All
animation and rendering features are available for scene graph objects and individually rendered objects alike.
The developer therefore does not need to choose between the immediate mode and the scene graph, but rather
can mix and match both within the same application.
Besides the API itself, a corresponding file format for efficient storage and transfer of all necessary data is also
defined. This data includes meshes, textures, scene hierarchies, material properties, animation keyframes, and
so on. Data is written into a file by content creation tools on a PC, and loaded into the API through the Loader
class.
The example applications at the end of this page provide a good means to get a quick overview of this API. Of
the individual classes, Graphics3D63 is perhaps the most important, because all rendering is done there. The
World204 class is crucial because it serves as the root of the scene graph structure. Object3D138 is the base
class of all objects that can be rendered or loaded from a file, and also the place where animations are applied.
We also recommend you to read the short section about documentation conventions below.

Documentation Conventions
The following general conventions are observed in the documentation of this API.
• Deferred exceptions. Most exceptions are thrown immediately upon method invocation, when erroneous
input is detected. However, the application is in some cases allowed to bring an object, or an aggregate of
objects, into an invalid state. There are four operations that may throw an exception as a result of their input
or host object being in an invalid state: the render methods in Graphics3D, the pick methods in Group,
the align method in Node, and the animate method in Object3D.
• Matrix notation. Matrices are denoted as upper case bold letters, and vectors as lower case bold letters. For
example, M denotes a matrix and v a vector. Matrices have 4x4 and vectors 4 elements, unless stated
otherwise. Vectors are always column vectors, and are consequently on the right hand side when multiplied
with a matrix: v’ = M v.
• Numeric intervals. Closed intervals are denoted with square brackets and open intervals with round
brackets. For example, [0, 10) denotes the values from zero to ten, including zero but not including ten.
Depending on the context, a numeric interval may consist of real numbers or integers.
• OpenGL references. All references to OpenGL in this specification are to version 1.3. See Related
Literature on the overview page.
• Coordinate systems. All 2D coordinate systems follow the MIDP convention where the origin is in the
upper left corner and integer coordinates are at pixel boundaries. By default, the 3D coordinate systems are
right-handed, and all rotations obey the right-hand rule: looking along the positive axis of rotation, positive
angles are clockwise. The camera coordinate system follows the OpenGL convention where the view
direction coincides with the negative z-axis, the positive x-axis points right and positive y-axis points up.
However, the application is free to set up left-handed 3D coordinate systems by use of transformation

7
javax.microedition.m3g

matrices.
• Diagram notation. The following common notation is used in diagrams that involve scene graph nodes
and node components.

Grey objects are "Nodes" -

White objects are components
groups or children of groups

Component
Arrows indicate references.
These components are
referenced by the node.
Node

Components can reference other

Component Component components, and nodes can
reference other nodes.

Package Discovery
Because of its optional nature, this API may not always be available on every platform. Each profile and
platform may have their own methods for J2ME package discovery as there is no universal method existing at
this time. An additional method for package discovery of the Mobile 3D Graphics API is by using a system
properties query. To discover this package, call System.getProperty with a key of
microedition.m3g.version. If the API is present, the value returned is the version of the API (currently
“1.0”). If the API is not present then the key is also not present and null will be returned.

General implementation requirements

Dynamic range and accuracy

The floating point format used for input and output is the standard IEEE float, having an 8-bit exponent and a
24-bit mantissa normalized to [1.0, 2.0). To facilitate efficient operation without floating point hardware,
implementations are allowed to substitute more constrained representations internally. The internal
representation must satisfy the following requirements:
• The input range must be at least [2-64, 263]. Any floating-point value in this range is legal as input to a
method that accepts floating point numbers. If the input value is not within that range, or is not a floating-
point number (NaN), the result is undefined.
• Elementary operations must have a range of at least [2-64, 263]. If the operands and the result of an
elementary arithmetic operation are within this range, the operation must not overflow or underflow. If the
operands and/or the result are not within that range, the result is undefined.
• The precision must be at least 16 significant bits. Provided that both the operands and the result of an
elementary arithmetic operation are within the range specified above, the result must be accurate to at least
16 significant bits.
These requirements apply to all arithmetic operations in this API, except triangle rasterization and per-fragment
operations, such as depth buffering, blending, and interpolation of colors and texture coordinates. In particular,
the requirements apply to node transformations in the scene graph; vertex coordinate, texture coordinate and
normal vector transformations; picking; keyframe interpolation; mesh morphing; skinning; and all methods in
the Transform class.

8
 javax.microedition.m3g

Blending, interpolation, comparisons and other operations on color, alpha and (screen-space) depth values must
have at least the same precision as the corresponding channel in the frame buffer. The minimum frame buffer
resolution is 1 bit for alpha and each color component, and 8 bits for depth. Of course, if some of the channels
do not exist, the corresponding values need not be computed.
All color and alpha blending operations are done component-wise and saturated to 1.0. In addition to the
general precision requirements, blending operations must also satisfy the following for all values of alpha and s
between [0, 1]:
alpha * s + (1 - alpha) * s = s

Correspondence of getters and setters

When querying the value of some property in the API, the returned value does not need to be exactly the same
that was set with the corresponding set method. Instead, it may be any value that produces an equivalent
result. The returned values are also not required to be in any “canonical” or “normalized” form. In the case of
node orientation, for example, there are a number of different axis-angle combinations that specify the same
orientation, and any one of them may be returned.
The returned value may also be an approximation of the original value, as long as the accuracy constraints for
the particular type of data are satisfied.

References to Objects
Unless otherwise stated, Object3Ds are held by reference, not by copying their data. Changes to the original
object therefore have immediate effect in the data structure as a whole. For example, changes to an Image2D
attached to the Background take effect without having to call the Background.setImage method again.
Where exceptions exist, these will be clearly documented as copying the values from the supplied Object3D.

Thread safety
Implementations must not crash or throw an exception as a result of being accessed from multiple threads at the
same time. However, the results of the requested operation in that case may be unpredictable.
No method in this API is allowed to block waiting for a resource, such as a rendering target, to be released. This
is to guarantee that no deadlock situations will occur. Also, any resources required by a method must be
released upon return. No method is allowed to leave its host object or other resources locked.

Pixel format conversion

Several different pixel formats are supported in rendering targets, textures, sprites, and background images.
Depending on the case, a mismatch between the source and destination pixel formats may require a format
conversion to be done. The general rules that are obeyed throughout the API are as follows:
• Luminance to RGB: The luminance value (L) is replicated to each of R, G and B.
• RGB to Luminance: Unspecified, but must take all components into account. For example, (R+G+B) / 3.
• Any missing luminance, color or alpha components are set to 1.0, unless explicitly stated otherwise.
More specific rules related to pixel formats are specified on a case-by-case basis in classes dealing with images
and the frame buffer. These include Graphics3D, Image2D, Texture2D, CompositingMode and Background.

Example applications
Two example MIDlets using the API are presented below. The first MIDlet is a pure immediate mode
application that displays a rotating, texture-mapped cube. It shows how to initialize a 3D graphics context, bind
it to a MIDP Canvas, and render some simple content with it. It also illustrates how to create a Mesh object
“manually”, that is, how to set up the coordinates, triangle connectivity, texture maps, and materials. In practice,

9
javax.microedition.m3g

this is usually not done programmatically, but with a 3D modeling tool. Loading a ready-made Mesh object
with all the necessary attributes is a simple matter of calling the load method in Loader.
The other example MIDlet is a retained mode application that plays back a ready-made animation that it
downloads over http.

10
 javax.microedition.m3g

(1) Immediate mode example MIDlet: Class MyCanvas

import javax.microedition.lcdui.*;
import javax.microedition.m3g.*;

public class MyCanvas extends Canvas {

private Graphics3D iG3D;

private Camera iCamera;
private Light iLight;
private float iAngle = 0.0f;
private Transform iTransform = new Transform();
private Background iBackground = new Background();
private VertexBuffer iVb; // positions, normals, colors, texcoords
private IndexBuffer iIb; // indices to iVB, forming triangle strips
private Appearance iAppearance; // material, texture, compositing, ...
private Material iMaterial = new Material();
private Image iImage;

/**
* Construct the Displayable.
*/
public MyCanvas() {
// set up this Displayable to listen to command events
setCommandListener(new CommandListener() {
public void commandAction(Command c, Displayable d) {
if (c.getCommandType() == Command.EXIT) {
// exit the MIDlet
MIDletMain.quitApp();
}
}
});
try {
init();
}
catch(Exception e) {
e.printStackTrace();
}
}

/**
* Component initialization.
*/
private void init() throws Exception {
// add the Exit command
addCommand(new Command(“Exit”, Command.EXIT, 1));

// get the singleton Graphics3D instance

iG3D = Graphics3D.getInstance();

// create a camera
iCamera = new Camera();
iCamera.setPerspective( 60.0f, // field of view
(float)getWidth()/ (float)getHeight(), // aspectRatio
1.0f, // near clipping plane
1000.0f ); // far clipping plane

// create a light
iLight = new Light();
iLight.setColor(0xffffff); // white light
iLight.setIntensity(1.25f); // overbright

// init some arrays for our object (cube)

// Each line in this array declaration represents a triangle strip for

// one side of a cube. The only primitive we can draw with is the

11
javax.microedition.m3g

// triangle strip so if we want to make a cube with hard edges we

// need to construct one triangle strip per face of the cube.
// 1 * * * * * 0
// * * *
// * * *
// * * *
// 3 * * * * * 2
// The ascii diagram above represents the vertices in the first line
// (the first tri-strip)
short[] vert = {
10, 10, 10, -10, 10, 10, 10,-10, 10, -10,-10, 10, // front
-10, 10,-10, 10, 10,-10, -10,-10,-10, 10,-10,-10, // back
-10, 10, 10, -10, 10,-10, -10,-10, 10, -10,-10,-10, // left
10, 10,-10, 10, 10, 10, 10,-10,-10, 10,-10, 10, // right
10, 10,-10, -10, 10,-10, 10, 10, 10, -10, 10, 10, // top
10,-10, 10, -10,-10, 10, 10,-10,-10, -10,-10,-10 }; // bottom

// create a VertexArray to hold the vertices for the object

VertexArray vertArray = new VertexArray(vert.length / 3, 3, 2);
vertArray.set(0, vert.length/3, vert);

// The per-vertex normals for the cube; these match with the vertices
// above. Each normal is perpendicular to the surface of the object at
// the corresponding vertex.
byte[] norm = {
0, 0, 127, 0, 0, 127, 0, 0, 127, 0, 0, 127,
0, 0,-127, 0, 0,-127, 0, 0,-127, 0, 0,-127,
-127, 0, 0, -127, 0, 0, -127, 0, 0, -127, 0, 0,
127, 0, 0, 127, 0, 0, 127, 0, 0, 127, 0, 0,
0, 127, 0, 0, 127, 0, 0, 127, 0, 0, 127, 0,
0,-127, 0, 0,-127, 0, 0,-127, 0, 0,-127, 0 };

// create a vertex array for the normals of the object

VertexArray normArray = new VertexArray(norm.length / 3, 3, 1);
normArray.set(0, norm.length/3, norm);

// per vertex texture coordinates

short[] tex = {
1, 0, 0, 0, 1, 1, 0, 1,
1, 0, 0, 0, 1, 1, 0, 1,
1, 0, 0, 0, 1, 1, 0, 1,
1, 0, 0, 0, 1, 1, 0, 1,
1, 0, 0, 0, 1, 1, 0, 1,
1, 0, 0, 0, 1, 1, 0, 1 };

// create a vertex array for the texture coordinates of the object

VertexArray texArray = new VertexArray(tex.length / 2, 2, 2);
texArray.set(0, tex.length/2, tex);

// the length of each triangle strip

int[] stripLen = { 4, 4, 4, 4, 4, 4 };

// create the VertexBuffer for our object

VertexBuffer vb = iVb = new VertexBuffer();
vb.setPositions(vertArray, 1.0f, null); // unit scale, zero bias
vb.setNormals(normArray);
vb.setTexCoords(0, texArray, 1.0f, null); // unit scale, zero bias

// create the index buffer for our object (this tells how to
// create triangle strips from the contents of the vertex buffer).
iIb = new TriangleStripArray( 0, stripLen );

// load the image for the texture

iImage = Image.createImage( “/texture.png” );

// create the Image2D (we need this so we can make a Texture2D)

Image2D image2D = new Image2D( Image2D.RGB, iImage );

12
 javax.microedition.m3g

// create the Texture2D and enable mipmapping

// texture color is to be modulated with the lit material color
Texture2D texture = new Texture2D( image2D );
texture.setFiltering(Texture2D.FILTER_NEAREST,
Texture2D.FILTER_NEAREST);
texture.setWrapping(Texture2D.WRAP_CLAMP,
Texture2D.WRAP_CLAMP);
texture.setBlending(Texture2D.FUNC_MODULATE);

// create the appearance

iAppearance = new Appearance();
iAppearance.setTexture(0, texture);
iAppearance.setMaterial(iMaterial);
iMaterial.setColor(Material.DIFFUSE, 0xFFFFFFFF); // white
iMaterial.setColor(Material.SPECULAR, 0xFFFFFFFF); // white
iMaterial.setShininess(100.0f);

iBackground.setColor(0xf54588); // set the background color

}

/**
* Paint the scene.
*/
protected void paint(Graphics g) {

// Bind the Graphics of this Canvas to our Graphics3D. The

// viewport is automatically set to cover the entire clipping
// rectangle of the Graphics object. The parameters indicate
// that z-buffering, dithering and true color rendering are
// enabled, but antialiasing is disabled.

iG3D.bindTarget(g, true,
Graphics3D.DITHER |
Graphics3D.TRUE_COLOR);

// clear the color and depth buffers

iG3D.clear(iBackground);

// set up the camera in the desired position

Transform transform = new Transform();
transform.postTranslate(0.0f, 0.0f, 30.0f);
iG3D.setCamera(iCamera, transform);

// set up a “headlight”: a directional light shining

// from the direction of the camera
iG3D.resetLights();
iG3D.addLight(iLight, transform);

// update our transform (this will give us a rotating cube)

iAngle += 1.0f;
iTransform.setIdentity();
iTransform.postRotate(iAngle, // rotate 1 degree per frame
1.0f, 1.0f, 1.0f); // rotate around this axis

// Render our cube. We provide the vertex and index buffers

// to specify the geometry; the appearance so we know what
// material and texture to use; and the transform to tell
// where to render the object
iG3D.render(iVb, iIb, iAppearance, iTransform);

// flush
iG3D.releaseTarget();
}
}

(2) Immediate mode example MIDlet: Class MIDletMain

13
javax.microedition.m3g

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
import java.util.*;

public class MIDletMain extends MIDlet

{
static MIDletMain instance;
MyCanvas displayable = new MyCanvas();
Timer iTimer = new Timer();

/**
* Construct the midlet.
*/
public MIDletMain() {
this.instance = this;
}

/**
* Main method.
*/
public void startApp() {
Display.getDisplay(this).setCurrent(displayable);
iTimer.schedule( new MyTimerTask(), 0, 40 );
}

/**
* Handle pausing the MIDlet.
*/
public void pauseApp() {
}

/**
* Handle destroying the MIDlet.
*/
public void destroyApp(boolean unconditional) {
}

/**
* Quit the MIDlet.
*/
public static void quitApp() {
instance.destroyApp(true);
instance.notifyDestroyed();
instance = null;
}

/**
* Our timer task for providing animation.
*/
class MyTimerTask extends TimerTask {
public void run() {
if( displayable != null ) {
displayable.repaint();
}
}
}
}

(3) Retained mode example MIDlet

import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

14
 javax.microedition.m3g

import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.CommandListener;

import java.util.Timer;
import java.util.TimerTask;

import javax.microedition.m3g.*;

public class JesterTestlet extends MIDlet implements CommandListener

{
private Display myDisplay = null;
private JesterCanvas myCanvas = null;

private Timer myRefreshTimer = new Timer();

private TimerTask myRefreshTask = null;

private Command exitCommand = new Command(“Exit”, Command.ITEM, 1);

private World myWorld = null;

/**
* JesterTestlet - default constructor.
*/
public JesterTestlet()
{
// Set up the user interface.
myDisplay = Display.getDisplay(this);
myCanvas = new JesterCanvas(this);
myCanvas.setCommandListener(this);
myCanvas.addCommand(exitCommand);
}

/**
* startApp()
*/
public void startApp() throws MIDletStateChangeException
{
myDisplay.setCurrent(myCanvas);

try
{
// Load a file.
Object3D[] roots =
Loader.load(“http://www.example.com/m3g/samples/simple.m3g”);

// Assume the world is the first root node loaded.

myWorld = (World)roots[0];

// Force a repaint so that we get the update loop started.

myCanvas.repaint();
}
catch(Exception e)
{
e.printStackTrace();
}
}

/**
* pauseApp()
*/
public void pauseApp()
{
// Release resources.
myWorld = null;

15
javax.microedition.m3g

/**
* destroyApp()
*/
public void destroyApp(boolean unconditional) throws MIDletStateChangeException
{
myRefreshTimer.cancel();
myRefreshTimer = null;

// Release resources.
myWorld = null;
}

/**
* MIDlet paint method.
*/
public void paint(Graphics g)
{
// We are not fully initialised yet; just return.
if(myCanvas == null || myWorld == null)
return;

// Delete any pending refresh tasks.

if(myRefreshTask != null)
{
myRefreshTask.cancel();
myRefreshTask = null;
}

// Get the current time.

long currentTime = System.currentTimeMillis();
// Update the world to the current time.
int validity = myWorld.animate((int)currentTime);

// Render to our Graphics.

Graphics3D myGraphics3D = Graphics3D.getInstance();
myGraphics3D.bindTarget(g);
myGraphics3D.render(myWorld);
myGraphics3D.releaseTarget();

// Subtract time taken to do the update.

validity -= System.currentTimeMillis() - currentTime;

if(validity < 1)
{ // The validity is too small; allow a minimum of 1ms.
validity = 1;
}

// If the validity is not infinite schedule a refresh task.

if(validity < 0x7fffffff)
{
// Create a new refresh task.
myRefreshTask = new RefreshTask();

// Schedule an update.
myRefreshTimer.schedule(myRefreshTask, validity);
}
}

/**
* Handle commands.
*/
public void commandAction(Command cmd, Displayable disp)
{
if (cmd == exitCommand)
{
try

16
 javax.microedition.m3g

{
destroyApp(false);
notifyDestroyed();
}
catch(Exception e)
{
e.printStackTrace();
}
}
}

/**
* Inner class for refreshing the view.
*/
private class RefreshTask extends TimerTask
{
public void run()
{
// Get the canvas to repaint itself.
myCanvas.repaint();
}
}

/**
* Inner class for handling the canvas.
*/
class JesterCanvas extends Canvas
{
JesterTestlet myTestlet;

/**
* Construct a new canvas
*/
JesterCanvas(JesterTestlet Testlet) { myTestlet = Testlet; }

/**
* Initialize self.
*/
void init() { }

/**
* Cleanup and destroy.
*/
void destroy() { }

/**
* Ask myTestlet to paint itself
*/
protected void paint(Graphics g) { myTestlet.paint(g); }
}
}

Class Summary
Classes
AnimationController19 Controls the position, speed and weight of an animation sequence.
AnimationTrack26 Associates a KeyframeSequence with an AnimationController and an animatable
property.
Appearance34 A set of component objects that define the rendering attributes of a Mesh or Sprite3D.
Background40 Defines whether and how to clear the viewport.

17
javax.microedition.m3g

Class Summary
Camera46 A scene graph node that defines the position of the viewer in the scene and the
projection from 3D to 2D.
CompositingMode52 An Appearance component encapsulating per-pixel compositing attributes.
Fog59 An Appearance component encapsulating attributes for fogging.
Graphics3D63 A singleton 3D graphics context that can be bound to a rendering target.
Group79 A scene graph node that stores an unordered set of nodes as its children.
Image2D85 A two-dimensional image that can be used as a texture, background or sprite image.
IndexBuffer91 Defines how to connect vertices to form a geometric object.
KeyframeSequence92 Encapsulates animation data as a sequence of time-stamped, vector-valued keyframes.
Light101 A scene graph node that represents different kinds of light sources.
Loader108 Downloads and deserializes scene graph nodes and node components, as well as entire
scene graphs.
Material113 An Appearance component encapsulating material attributes for lighting computations.
Mesh118 A scene graph node that represents a 3D object defined as a polygonal surface.
MorphingMesh123 A scene graph node that represents a vertex morphing polygon mesh.
Node129 An abstract base class for all scene graph nodes.
Object3D138 An abstract base class for all objects that can be part of a 3D world.
PolygonMode146 An Appearance component encapsulating polygon-level attributes.
RayIntersection151 A RayIntersection object is filled in by the pick methods in Group.
SkinnedMesh155 A scene graph node that represents a skeletally animated polygon mesh.
Sprite3D162 A scene graph node that represents a 2-dimensional image with a 3D position.
Texture2D169 An Appearance component encapsulating a two-dimensional texture image and a set of
attributes specifying how the image is to be applied on submeshes.
Transform178 A generic 4x4 floating point matrix, representing a transformation.
Transformable185 An abstract base class for Node and Texture2D, defining common methods for
manipulating node and texture transformations.
TriangleStripArray191 TriangleStripArray defines an array of triangle strips.
VertexArray194 An array of integer vectors representing vertex positions, normals, colors, or texture
coordinates.
VertexBuffer197 VertexBuffer holds references to VertexArrays that contain the positions, colors,
normals, and texture coordinates for a set of vertices.
World204 A special Group node that is a top-level container for scene graphs.

18
 javax.microedition.m3g AnimationController

javax.microedition.m3g
AnimationController
Declaration
public class AnimationController extends Object3D138

java.lang.Object
|
+--javax.microedition.m3g.Object3D138
|
+--javax.microedition.m3g.AnimationController

Description
Controls the position, speed and weight of an animation sequence.
In anything other than the simplest scenes, an animation sequence will require control of more than one
property of more than one object. For example, a jointed figure performing a single gesture is usually thought of
as a single animation, yet it involves the coordinated control of the position and orientation of many different
objects.
We define an animation sequence to mean a set of individual AnimationTracks that are controlled by a single
AnimationController. Each AnimationTrack object contains all the data required to control a single animatable
property on one target object.
An AnimationController object enables its associated animation sequence as a whole to be paused, stopped,
restarted, fast-forwarded, rewound, arbitrarily repositioned, or deactivated. More formally, it defines a linear
mapping from world time to sequence time.
The detailed behaviour of how the data flows through the animation system as a whole is documented in the
AnimationTrack26 class.

Animation application
In both immediate and retained mode, animations are explicitly applied to target objects by calling the
animate method on the target Object3D itself. This re-evaluates the values of all object properties that have
one or more animations attached. Animations are also applied to the children of the target object, so the
application is free to choose between calling myWorld.animate to animate everything in myWorld at once,
or applying animations to more fine-grained groups of objects individually.
Animation controllers have an active interval, specified by minimum and maximum world time values, during
which the animation controller is active. Animations controlled by inactive animation controllers have no effect
on their target objects and are simply ignored during animation application.

Animation weighting
Each animation controller has a weight associated with it. The contributions of all active animations targeting
the same property at the same time are blended together by their respective weights. Formally, the value of a
scalar property P as a function of weights wi and contributions Pi is:
P = sum [ wi Pi ]
For vector-valued properties, the above formula is applied for each vector component separately. For most types
of animation, the simple weighted sum as shown above is sufficient, but for orientation values the
implementation is required to normalize the resulting quaternion.

19
AnimationController javax.microedition.m3g

Timing and speed control

AnimationController specifies a linear mapping between world time, passed in to Object3D.animate, and
sequence time that is used in sampling the associated keyframe data.
The sequence time is calculated directly from the given world time at each call to animate, instead of storing
it internally. This is to avoid undesirable accumulation of rounding errors and any artifacts potentially resulting
from that. It also simplifies the usage of the animation system by making it effectively stateless (as opposed to a
traditional state machine design).
The mapping from world time to sequence time is parameterized by three constants, specified in
AnimationController, and one variable, the world time, that is passed in to animate. The formula for
calculating the sequence time ts corresponding to a given world time tw is:
ts = tsref + s (tw - twref)
where
ts = the computed sequence time
tw = the given world time
tsref = the reference sequence time
twref = the reference world time
s = the speed; sequence time per world time

The reference point (twref, tsref) is specified with the setPosition method and the speed with the
setSpeed method (note that setting the speed may also change the reference point).
Sequence time can be visualized, in a coordinate system where world time is on the horizontal and sequence
time on the vertical axis, as a line having slope s and passing through the point (twref, tsref).
As an example of the relationship between world time and sequence time, imagine a world where the current
time is 5000 milliseconds since the start. An animation was started (from 0 ms sequence time) at 3000 ms,
running at half speed. The animation was started 2000 ms ago, but because the speed is 0.5, the actual required
sequence time tsref is 1000 ms. Here, we would have tw = 5000 ms, twref = 3000 ms, tsref = 0 ms, and s = 0.5 in
the formula above.
Note that the unit of time is not explicitly specified anywhere in the API or the file format. It is strongly
recommended that applications and content creation tools express times in milliseconds by default. Arbitrary
units can, however, be used in specific applications if mandated by range or precision requirements.

Synchronized animation
We assume that synchronization of animation with other media types is only based on the world time passed
from the controlling application. No synchronization events or other mechanisms are provided for this purpose.
In the case of synchronizing animation to music, for example, the current elapsed time is often available directly
from the music player library.

Example usage
As an example of using animation, consider a case where we want a light source to pulsate between red and
green, moving along a curved path. In both immediate and retained mode, this involves creating keyframe
sequences and associating them with the light node, as illustrated in Example 1 below.
To apply the animation to the light object in our rendering loop, we must call the animate method, as shown
in Example 2.

20
 javax.microedition.m3g AnimationController

(1) Creating an animation

Light light = new Light(); // Create a light node

// Load a motion path from a stream, assuming it's the first

// object there

Object3D[] objects = Loader.load(“http://www.ex.com/ex.m3g”);

KeyframeSequence motion = (KeyframeSequence) objects[0];

// Create a color keyframe sequence, with keyframes at 0 ms

// and 500 ms, and a total duration of 1000 ms. The animate
// method will throw an exception if it encounters a
// KeyframeSequence whose duration has not been set or whose
// keyframes are out of order. Note that the Loader
// automatically validates any sequences that are loaded from
// a file.

KeyframeSequence blinking = new KeyframeSequence(2, 3,

KeyframeSequence.LINEAR);
blinking.setKeyframe(0, 0, new float[] { 1.0f, 0.0f, 0.0f });
blinking.setKeyframe(1, 500, new float[] { 0.0f, 1.0f, 0.0f });
blinking.setDuration(1000);

AnimationTrack blink = new AnimationTrack(blinking,

AnimationTrack.COLOR);
AnimationTrack move = new AnimationTrack(motion,
AnimationTrack.TRANSLATION);
light.addAnimationTrack(blink);
light.addAnimationTrack(move);

// Create an AnimationController and make it control both the

// blinking and the movement of our light

AnimationController lightAnim = new AnimationController();

blink.setController(lightAnim);
move.setController(lightAnim);

// Start the animation when world time reaches 2 seconds, stop

// at 5 s. There is only one reference point for this
// animation: sequence time must be zero at world time 2000
// ms. The animation will be running at normal speed (1.0, the
// default).

lightAnim.setActiveInterval(2000, 5000);
lightAnim.setPosition(0, 2000);

(2) Applying the animation during rendering

appTime += 30; // advance time by 30 ms each frame

light.animate(appTime);

// Assume 'myGraphics3D' is the Graphics3D object we draw into.

// In immediate mode, node transforms are ignored, so we get
// our animated transformation into a local Transform object,
// “lightToWorld”. As its name implies, the transformation is
// from the Light node's local coordinates to world space.

light.getTransform(lightToWorld);
myGraphics3D.resetLights();
myGraphics3D.addLight(light, lightToWorld);

See Also: AnimationTrack26, KeyframeSequence92, Object3D138

21
AnimationController javax.microedition.m3g
AnimationController()

Member Summary
Constructors
AnimationController()22
Methods
int getActiveIntervalEnd()23
int getActiveIntervalStart()23
float getPosition(int worldTime)23
float getSpeed()23
float getWeight()23
void setActiveInterval(int start, int end)24
void setPosition(float sequenceTime, int worldTime)24
void setSpeed(float speed, int worldTime)24
void setWeight(float weight)25

Inherited Member Summary

Methods inherited from class Object
equals(Object), getClass(), hashCode(), notify(), notifyAll(), toString(), wait(),
wait(), wait()

Methods inherited from class Object3D138

addAnimationTrack(AnimationTrack)140, animate(int)141, duplicate()142, find(int)142,
getAnimationTrack(int)142, getAnimationTrackCount()143, getReferences(Object3D[])143,
getUserID()144, getUserObject()144, removeAnimationTrack(AnimationTrack)144,
setUserID(int)144, setUserObject(Object)145

Constructors
AnimationController()
public AnimationController()

Creates a new AnimationController object. The default values for the new object are:
• active interval: [0, 0) (always active)
• blending weight: 1.0
• speed: 1.0
• reference point: (0, 0)

22
 javax.microedition.m3g AnimationController
getActiveIntervalEnd()

Methods
getActiveIntervalEnd()
public int getActiveIntervalEnd()

Retrieves the ending time of the current active interval of this animation controller, in world time units. The
value returned is the same that was last set with setActiveInterval, or if it has not been called yet,
the default value set at construction.
Returns: the ending time of the active interval
See Also: setActiveInterval24

getActiveIntervalStart()
public int getActiveIntervalStart()

Retrieves the starting time of the current active interval of this animation controller, in world time units.
The value returned is the same that was last set with setActiveInterval, or if it has not been called
yet, the default value set at construction.
Returns: the starting time of the active interval
See Also: setActiveInterval24

getPosition(int)
public float getPosition(int worldTime)

Retrieves the sequence time that corresponds to the given world time. The returned value is computed with
the formula given in the class description. Note that because the result may be a fractional number, it is
returned as a float, not integer.
Parameters:
worldTime - world time to get the corresponding sequence time of
Returns: animation sequence position in number of time units elapsed since the beginning of this
animation, until worldTime
See Also: setPosition24

getSpeed()
public float getSpeed()

Retrieves the currently set playback speed of this animation controller.

Returns: the current playback speed
See Also: setSpeed24

getWeight()
public float getWeight()

Retrieves the currently set blending weight for this animation controller.
Returns: the current blending weight
See Also: setWeight25

23
AnimationController javax.microedition.m3g
setActiveInterval(int, int)

setActiveInterval(int, int)
public void setActiveInterval(int start, int end)

Sets the world time interval during which this animation controller is active.
This animation controller will subsequently be active when the world time t is such that start <= t <
end, and inactive outside of that range. As a special case, if start and end are set to the same value, this
animation controller is always active.
Note that changing the active interval has no effect on the mapping from world time to sequence time.
Parameters:
start - the starting time of the active interval, in world time units (inclusive)
end - the ending time of the active interval, in world time units (exclusive)
Throws:
java.lang.IllegalArgumentException - if start > end
See Also: getActiveIntervalStart23, getActiveIntervalEnd23

setPosition(float, int)
public void setPosition(float sequenceTime, int worldTime)

Sets a new playback position, relative to world time, for this animation controller. This sets the internal
reference point (twref, tsref) to (worldTime, sequenceTime) to shift the animation to the new position.
Parameters:
sequenceTime - the desired playback position in sequence time units
worldTime - the world time at which the sequence time must be equal to sequenceTime
See Also: getPosition23

setSpeed(float, int)
public void setSpeed(float speed, int worldTime)

Sets a new playback speed for this animation. The speed is set as a factor of the nominal speed of the
animation: 1.0 is normal playback speed (as specified by the keyframe times in the associated animation
tracks), 2.0 is double speed, and -1.0 is reverse playback at normal speed. A speed of 0.0 freezes the
animation.
The speed setting effectively specifies how much to advance the internal playback position of this
animation for a given increment in the global world time.
The internal reference point is modified so that sequence time at the given world time remains unchanged.
This allows the application to change the speed without causing the animation to “jump” forward or
backward. To get the desired effect, the application should pass its current world time to this method. This
is the time that the application has most recently used in animate, or the time that it is next going to use.
The reference point (twref, tsref) and speed (s) are updated based on the given world time and speed as
follows:
twref ’ = worldTime
tsref ’ = getPosition(worldTime)
s’ = speed

24
 javax.microedition.m3g AnimationController
setWeight(float)

Note that the computation of the new reference sequence time takes place before updating the speed. See
the class description for the formula that getPosition uses, and for more discussion on animation
timing.
Parameters:
speed - new playback speed; 1.0 is normal speed
worldTime - reference world time; the value of sequence time at this point will remain constant
during the speed change
See Also: getSpeed23

setWeight(float)
public void setWeight(float weight)

Sets the blending weight for this animation controller. The blending weight must be positive or zero.
Setting the weight to zero disables this animation controller; that is, the controller is subsequently not active
even within its active range. If the weight is non-zero, the animations controlled by this controller
contribute to their target properties as described in the class description.
Parameters:
weight - the new blending weight
Throws:
java.lang.IllegalArgumentException - if weight < 0
See Also: getWeight23

25
AnimationTrack javax.microedition.m3g
setWeight(float)

javax.microedition.m3g
AnimationTrack
Declaration
public class AnimationTrack extends Object3D138

java.lang.Object
|
+--javax.microedition.m3g.Object3D138
|
+--javax.microedition.m3g.AnimationTrack

Description
Associates a KeyframeSequence with an AnimationController and an animatable property.
An animatable property is a scalar or vector variable that the animation system can directly update; for instance,
the orientation of a Node. Animatable properties are identified by the symbolic constants listed below. Some
animatable properties are only applicable to one class, such as the SHININESS of a Material, while others
apply to two or more classes.
Most classes derived from Object3D have one or more animatable properties. An Object3D instance with
animatable properties is called an animatable object. Each animatable property of an animatable object
constitutes a unique animation target.
Each animatable object may reference zero or more AnimationTracks. Each of these, when activated by their
respective AnimationControllers, is in charge of updating one of the animation targets of the animatable object.
The values assigned to the targets are determined by sampling the KeyframeSequence objects referenced by the
AnimationTrack objects. Each KeyframeSequence can be referenced by multiple AnimationTracks, allowing
the keyframe data to be shared.
Each AnimationTrack is associated with exactly one AnimationController, one KeyframeSequence, and one
animatable property, but it may be associated with multiple animation targets. In other words, it can animate the
same property in many different objects simultaneously. It is also possible to have several AnimationTrack
objects associated with a single animation target. In this case, the final value of the animation target is a linear
combination of the values derived from the individual AnimationTracks, weighted by their respective
AnimationController weights.

Implementation guidelines

Clamping of interpolated values

Animation keyframes are input as floating point, and the values produced after interpolation and blending are
also in floating point. When applied to their target property, the values must be mapped to the closest
representable value that is valid for the property in question. For example, values for a floating point property
must be clamped to the valid range for that property; values for an integer property rounded to the closest
integer; and values for a boolean property interpreted as true when the value produced by animation is greater
than or equal to 0.5, false if less. Exceptions to this rule are stated explicitly if necessary.
In summary, applying an animated quantity to its target property must never result in an exception or otherwise
illegal state.

26
 javax.microedition.m3g AnimationTrack
setWeight(float)

Example implementation
When the whole scene graph or a subtree of objects is updated (using a call to Object3D.animate), the
world time, maintained by the controlling application, is passed to each animatable object. In turn, each
animatable object passes the world time to each of the AnimationTrack objects which are bound to it.
The AnimationTrack object then checks to see if the current world time falls within the active interval of its
associated AnimationController object. If not, then no further action is taken by this AnimationTrack. If no
active AnimationTrack objects are found for an animation target, the value of that target is unchanged. Note,
however, that animation targets are independent of each other, and other targets in the same object may still
change.
If the AnimationController is active, it is used to determine the sequence time for the animation. (Details of this
calculation can be found in the AnimationController class description.) The sequence time is then used to obtain
an interpolated value from the KeyframeSequence object. (Details of interpolation are in the
KeyframeSequence class description.) This sample is then multiplied by the weight factor of the
AnimationController object and applied to the target property. If multiple AnimationTrack objects target the
same property, they are blended together according to the weights of their respective AnimationController
objects; see AnimationController for more details on animation blending.

See Also: KeyframeSequence92, AnimationController19,

Object3D.addAnimationTrack140

Member Summary
Fields
static int ALPHA28
static int AMBIENT_COLOR28
static int COLOR28
static int CROP29
static int DENSITY29
static int DIFFUSE_COLOR29
static int EMISSIVE_COLOR29
static int FAR_DISTANCE29
static int FIELD_OF_VIEW30
static int INTENSITY30
static int MORPH_WEIGHTS30
static int NEAR_DISTANCE30
static int ORIENTATION30
static int PICKABILITY31
static int SCALE31
static int SHININESS31
static int SPECULAR_COLOR31
static int SPOT_ANGLE31
static int SPOT_EXPONENT32
static int TRANSLATION32
static int VISIBILITY32
Constructors
AnimationTrack(KeyframeSequence sequence, int property)32
Methods
AnimationController getController()32
KeyframeSequence getKeyframeSequence()33

27
AnimationTrack javax.microedition.m3g
ALPHA

Member Summary
int getTargetProperty()33
void setController(AnimationController controller)33

Inherited Member Summary

Methods inherited from class Object
equals(Object), getClass(), hashCode(), notify(), notifyAll(), toString(), wait(),
wait(), wait()

Methods inherited from class Object3D138

addAnimationTrack(AnimationTrack)140, animate(int)141, duplicate()142, find(int)142,
getAnimationTrack(int)142, getAnimationTrackCount()143, getReferences(Object3D[])143,
getUserID()144, getUserObject()144, removeAnimationTrack(AnimationTrack)144,
setUserID(int)144, setUserObject(Object)145

Fields
ALPHA
public static final int ALPHA

Specifies the alpha factor of a Node, or the alpha component of the Background color, Material diffuse
color, or VertexBuffer default color as an animation target. The interpolated value is clamped to the range
[0, 1].
Number of components required: 1

AMBIENT_COLOR
public static final int AMBIENT_COLOR

Specifies the ambient color of a Material as an animation target. The interpolated value of each color
component is clamped to the range [0, 1].
Number of components required: 3 (RGB)

COLOR
public static final int COLOR

Specifies the color of a Light, Background, or Fog, or the texture blend color in Texture2D, or the
VertexBuffer default color as an animation target. The interpolated value of each color component is
clamped to the range [0, 1].
Note that the alpha component of the background color or default color is targeted separately using the
identifier ALPHA (the other COLOR targets do not have an alpha component).
Number of components required: 3 (RGB)

28
 javax.microedition.m3g AnimationTrack
CROP

CROP
public static final int CROP

Specifies the cropping parameters of a Sprite3D or Background as an animation target. The required
parameters are the X and Y coordinates of the crop rectangle upper left corner, and the width and height of
the crop rectangle, in that order.
The X and Y parameters may take on any value, regardless of whether the target object is a Sprite3D or
Background. The width and height, however, have differing limits depending on the target.
In case of a Background target, negative values of width and height are clamped to zero. In case of a
Sprite3D target, they are clamped to the range [-N, N], where N is the implementation specific maximum
sprite crop size. Recall that negative values of width and height cause the displayed image to be flipped in
the corresponding dimensions.
Number of components required: 2 (X, Y) or 4 (X, Y, width, height)

DENSITY
public static final int DENSITY

Specifies the fog density in Fog as an animation target. If the interpolated value is negative, it is clamped to
zero.
Number of components required: 1

DIFFUSE_COLOR
public static final int DIFFUSE_COLOR

Specifies the diffuse color of a Material as an animation target. The interpolated value of each color
component is clamped to the range [0, 1].
Note that the alpha component of the diffuse color is targeted separately, using the identifier ALPHA.
Number of components required: 3 (RGB)

EMISSIVE_COLOR
public static final int EMISSIVE_COLOR

Specifies the emissive color of a Material as an animation target. The interpolated values of the color
components are clamped to the range [0, 1].
Number of components required: 3 (RGB)

FAR_DISTANCE
public static final int FAR_DISTANCE

Specifies the far distance of a Camera or Fog as an animation target. In case of a Camera target in
perspective mode, negative values and zero are clamped to the smallest representable positive number. In
case of a Fog target, or a camera target in parallel mode, the value is not clamped.
Animating any of the camera parameters (near, far, field of view) only has an effect if the camera is in
perspective or parallel mode.
Number of components required: 1

29
AnimationTrack javax.microedition.m3g
FIELD_OF_VIEW

FIELD_OF_VIEW
public static final int FIELD_OF_VIEW

Specifies the field of view of a Camera as an animation target. The interpolated value is clamped to the
range (0, 180) in case of a perspective Camera. In case of a parallel camera, negative values and zero are
clamped to the smallest representable positive number.
Animating any of the camera parameters (near, far, field of view) only has an effect if the camera is in
perspective or parallel mode.
Number of components required: 1

INTENSITY
public static final int INTENSITY

Specifies the intensity of a Light as an animation target.

Number of components required: 1

MORPH_WEIGHTS
public static final int MORPH_WEIGHTS

Specifies the morph target weights of a MorphingMesh123 as an animation target. If there are N morph
targets in the target mesh, the associated keyframes should be N-element vectors.
Since there is no direct reference from this object to its associated MorphingMesh node, there is no way to
check at construction time that the number of vector components matches the number of morph targets.
Denoting the number of components in the keyframe vectors by V, the following rules apply in case of a
mismatch:
If V < N, then morph target weights are set as
w[i] = v[i], for 0 <= i < V
w[i] = 0.0, for V <= i < N
If V > N, then morph target weights are set as
w[i] = v[i], for 0 <= i < N
v[i] ignored for N <= i < V
Number of components required: N

NEAR_DISTANCE
public static final int NEAR_DISTANCE

Specifies the near distance of a Camera or Fog as an animation target. In case of a Camera target in
perspective mode, negative values and zero are clamped to the smallest representable positive number. In
case of a Fog target, or a camera target in parallel mode, the value is not clamped.
Animating any of the camera parameters (near, far, field of view) only has an effect if the camera is in
perspective or parallel mode.
Number of components required: 1

ORIENTATION
public static final int ORIENTATION

30
 javax.microedition.m3g AnimationTrack
PICKABILITY

Specifies the orientation component of the transformation of a Transformable object as an animation target.
The orientation is specified as a 4-element vector defining a quaternion. Quaternion keyframes are
automatically normalized before interpolation; they need not be unit length on input. The quaternion
components in the keyframes are ordered as follows:
• v[0] coefficient of i (related to the x component of the rotation axis)
• v[1] coefficient of j (related to the y component of the rotation axis)
• v[2] coefficient of k (related to the z component of the rotation axis)
• v[3] the scalar component (related to the rotation angle)
Number of components required: 4

PICKABILITY
public static final int PICKABILITY

Specifies the picking enable flag of a Node as an animation target.

Number of components required: 1

SCALE
public static final int SCALE

Specifies the scaling component of the transformation of a Transformable object as an animation target.
The number of keyframe components in the associated KeyframeSequence can be either one or three, for
uniform or non-uniform scaling, respectively.
Number of components required: 1 or 3 (XYZ)

SHININESS
public static final int SHININESS

Specifies the shininess of a Material as an animation target. The interpolated value is clamped to the range
[0, 128].
Number of components required: 1

SPECULAR_COLOR
public static final int SPECULAR_COLOR

Specifies the specular color of a Material as an animation target. The interpolated value of each color
component is clamped to the range [0, 1].
Number of components required: 3 (RGB)

SPOT_ANGLE
public static final int SPOT_ANGLE

Specifies the spot angle of a Light as an animation target. The interpolated value is clamped to the range [0,
90].
Number of components required: 1

31
AnimationTrack javax.microedition.m3g
SPOT_EXPONENT

SPOT_EXPONENT
public static final int SPOT_EXPONENT

Specifies the spot exponent of a Light as an animation target. The interpolated value is clamped to the range
[0, 128].
Number of components required: 1

TRANSLATION
public static final int TRANSLATION

Specifies the translation component of the transformation of a Transformable object as an animation target.
Number of components required: 3 (XYZ)

VISIBILITY
public static final int VISIBILITY

Specifies the rendering enable flag of a Node as an animation target.

Number of components required: 1

Constructors
AnimationTrack(KeyframeSequence, int)
public AnimationTrack(javax.microedition.m3g.KeyframeSequence92 sequence, int property)

Creates an animation track with the given keyframe sequence targeting the given property. The keyframe
sequence must be compatible with the target property; for example, to animate the translation component of
a transformation, the keyframes must be 3-element vectors.
No controller is initially attached to the track.
Parameters:
sequence - a KeyframeSequence containing the keyframe data for this animation track
property - one of ALPHA, ..., VISIBILITY
Throws:
java.lang.NullPointerException - if sequence is null
java.lang.IllegalArgumentException - if property is not one of the symbolic
constants listed above
java.lang.IllegalArgumentException - if sequence is not compatible with property

Methods
getController()
public javax.microedition.m3g.AnimationController19 getController()

Retrieves the animation controller used for controlling this animation track.

32
 javax.microedition.m3g AnimationTrack
getKeyframeSequence()

Returns: the AnimationController object which defines the active state and sequence time for this
animation sequence, as set by setController. If no controller has yet been attached, this method
returns null
See Also: setController33

getKeyframeSequence()
public javax.microedition.m3g.KeyframeSequence92 getKeyframeSequence()

Returns the keyframe sequence object which defines the keyframe values for this animation track.
Returns: the KeyframeSequence object which defines the keyframe values

getTargetProperty()
public int getTargetProperty()

Returns the property targeted by this AnimationTrack. The target property is one of the symbolic constants
listed above.
Returns: the object property targeted by this track

setController(AnimationController)
public void setController(javax.microedition.m3g.AnimationController19 controller)

Specifies the animation controller to be used for controlling this animation track. The controller determines
the mapping from world time to sequence time, the speed of animation, and the active interval for all tracks
under its control.
Parameters:
controller - an AnimationController object which defines the active state and sequence time for
this animation sequence; if this is null then the behaviour is equivalent to associating this object with an
inactive animation controller
See Also: getController32

33
Appearance javax.microedition.m3g
setController(AnimationController)

javax.microedition.m3g
Appearance
Declaration
public class Appearance extends Object3D138

java.lang.Object
|
+--javax.microedition.m3g.Object3D138
|
+--javax.microedition.m3g.Appearance

Description
A set of component objects that define the rendering attributes of a Mesh or Sprite3D.
Appearance attributes are grouped into component objects, each encapsulating a set of properties that are
functionally and logically related to each other. This division helps applications to conserve memory by sharing
component objects across multiple meshes and sprites. The Appearance component classes and a summary of
their contents are presented in the figure below.

Contains information for

lighting the object, such as
color and shininess.
Appearance Material

Contains information about

polygons, such as winding
Polygon rule and culling mode.
Mode
Contains information about
blending this object into the
Compositing scene as a whole.
Mode
Defines how to shade this
object based on its distance
from the camera.
Fog

Image used as a texture.

Often shared between
multiple Texture2D objects.
Texture2D Image2D

Texture2D Image2D

Contains information about how to

apply texture to this object. The
maximum number of textures per
appearance depends on the number
of texture units supported.

34
 javax.microedition.m3g Appearance
setController(AnimationController)

All components of a newly created Appearance object are initialized to null. It is completely legal for any or all
of the components to be null even when rendering. The behavior when each of the components is null is as
follows:
• If a Texture2D is null, the corresponding texturing unit is disabled.
• If the PolygonMode is null, default values are used.
• If the CompositingMode is null, default values are used.
• If the Material is null, lighting is disabled.
• If the Fog is null, fogging is disabled.
Using a null Appearance on a submesh (or sprite) disables rendering and picking of that submesh (or sprite). An
Appearance must always be provided for an object in order to make it visible.

Implementation guidelines
By default, everything in Appearance works exactly the same way as in OpenGL 1.3. As a general exception,
the color index (palette) mode is not supported. Other than that, any deviations from the OpenGL 1.3
specification are documented explicitly in the individual Appearance component classes.

Member Summary
Constructors
Appearance()36
Methods
CompositingMode getCompositingMode()36
Fog getFog()36
int getLayer()36
Material getMaterial()37
PolygonMode getPolygonMode()37
Texture2D getTexture(int index)37
void setCompositingMode(CompositingMode compositingMode)37
void setFog(Fog fog)37
void setLayer(int layer)37
void setMaterial(Material material)38
void setPolygonMode(PolygonMode polygonMode)38
void setTexture(int index, Texture2D texture)38

Inherited Member Summary

Methods inherited from class Object
equals(Object), getClass(), hashCode(), notify(), notifyAll(), toString(), wait(),
wait(), wait()

Methods inherited from class Object3D138

35
Appearance javax.microedition.m3g
Appearance()

Inherited Member Summary

addAnimationTrack(AnimationTrack)140, animate(int)141, duplicate()142, find(int)142,
getAnimationTrack(int)142, getAnimationTrackCount()143, getReferences(Object3D[])143,
getUserID()144, getUserObject()144, removeAnimationTrack(AnimationTrack)144,
setUserID(int)144, setUserObject(Object)145

Constructors
Appearance()
public Appearance()

Constructs an Appearance object with default values. The default values are:
• rendering layer : 0
• polygon mode : null (use defaults)
• compositing mode : null (use defaults)
• all textures : null (all texturing units disabled)
• material : null (lighting disabled)
• fog : null (fogging disabled)

Methods
getCompositingMode()
public javax.microedition.m3g.CompositingMode52 getCompositingMode()

Returns the current CompositingMode for this Appearance.

Returns: the current CompositingMode object, or null if no CompositingMode is set
See Also: setCompositingMode37

getFog()
public javax.microedition.m3g.Fog59 getFog()

Returns the current fogging attributes for this Appearance.

Returns: the current Fog object, or null if fogging is disabled
See Also: setFog37

getLayer()
public int getLayer()

Gets the current rendering layer for this Appearance.

Returns: the current rendering layer; this is always in the range [-63, 63]
See Also: setLayer37

36
 javax.microedition.m3g Appearance
getMaterial()

getMaterial()
public javax.microedition.m3g.Material113 getMaterial()

Returns the current Material for this Appearance.

Returns: the current Material object, or null if lighting is disabled
See Also: setMaterial38

getPolygonMode()
public javax.microedition.m3g.PolygonMode146 getPolygonMode()

Returns the current PolygonMode for this Appearance.

Returns: the current PolygonMode object, or null if no PolygonMode is set
See Also: setPolygonMode38

getTexture(int)
public javax.microedition.m3g.Texture2D169 getTexture(int index)

Retrieves the current texture image and its attributes for the given texturing unit.
Parameters:
index - texturing unit index
Returns: the current texture object of the specified texturing unit, or null if the unit is disabled
Throws:
java.lang.IndexOutOfBoundsException - if index is not a valid texturing unit index
See Also: setTexture38

setCompositingMode(CompositingMode)
public void setCompositingMode(javax.microedition.m3g.CompositingMode52 compositingMode)

Sets the CompositingMode to use for this Appearance. If the CompositingMode is set to null, the default
values are used.
Parameters:
compositingMode - a CompositingMode object, or null to use the defaults
See Also: getCompositingMode36

setFog(Fog)
public void setFog(javax.microedition.m3g.Fog59 fog)

Sets the fogging attributes to use for this Appearance. If the Fog object is set to null, fogging is disabled.
Parameters:
fog - a Fog object, or null to disable fogging
See Also: getFog36

setLayer(int)
public void setLayer(int layer)

37
Appearance javax.microedition.m3g
setMaterial(Material)

Sets the rendering layer for this Appearance. When rendering a World, Group or Mesh, submeshes and
sprites are guaranteed to be rendered in the order of ascending layers. That is, all submeshes and sprites
with an appearance at a lower layer are rendered prior to any submeshes or sprites at the higher layers.
Furthermore, all opaque submeshes and sprites at a specific layer are rendered prior to any blended
submeshes or sprites at the same layer. A submesh or a sprite is defined to be opaque if it uses the
REPLACE blending mode (see CompositingMode), and blended otherwise.
Implementations are free to do any additional state sorting as long as the aforementioned constraints are
met. To allow implementations to operate as efficiently as possible, applications should only use layering
constraints when required. As a result of the rules above, the default layer of zero should be sufficient for
most uses. Cases where non-zero layers may be useful include background geometry, sky boxes, lens flares,
halos, and other special effects.
Note that the rendering layer has no effect on picking.
Parameters:
layer - the rendering layer for submeshes and sprites having this Appearance
Throws:
java.lang.IndexOutOfBoundsException - if layer is not in [-63, 63]
See Also: getLayer36, Mesh118

setMaterial(Material)
public void setMaterial(javax.microedition.m3g.Material113 material)

Sets the Material to use when lighting this Appearance. If the Material is set to null, lighting is disabled. See
the Material class description for more information.
Parameters:
material - a Material object, or null to disable lighting
See Also: getMaterial37

setPolygonMode(PolygonMode)
public void setPolygonMode(javax.microedition.m3g.PolygonMode146 polygonMode)

Sets the PolygonMode to use for this Appearance. If the PolygonMode is set to null, the default values are
used.
Parameters:
polygonMode - a PolygonMode object, or null to use the defaults
See Also: getPolygonMode37

setTexture(int, Texture2D)
public void setTexture(int index, javax.microedition.m3g.Texture2D169 texture)

Sets the texture image and its attributes for the given texturing unit. If the texture object is set to null, the
specified texturing unit is disabled.
Parameters:
index - texturing unit index
texture - a texture object for the specified texturing unit, or null to disable the unit
Throws:
java.lang.IndexOutOfBoundsException - if index is not a valid texturing unit index

38
 javax.microedition.m3g Appearance
setTexture(int, Texture2D)

See Also: getTexture37

39
Background javax.microedition.m3g
setTexture(int, Texture2D)

javax.microedition.m3g
Background
Declaration
public class Background extends Object3D138

java.lang.Object
|
+--javax.microedition.m3g.Object3D138
|
+--javax.microedition.m3g.Background

Description
Defines whether and how to clear the viewport.
The portions of the frame buffer that correspond to the current viewport are cleared according to a given
Background object. In retained mode (that is, when rendering a World), the Background object associated with
the World is used. In immediate mode, a Background object is given as a parameter to clear. In absence of a
Background object, the default values specified in the constructor are used.
Clearing can be enabled and disabled individually for the color buffer and the depth buffer. The color buffer is
cleared using the background color and/or the background image, as specified below. If the background image
is set to null (the initial value), only the background color is used. The depth buffer is always cleared to the
maximum depth value.

Background image
The background image is stored as a reference to an Image2D. If the referenced Image2D is modified by the
application, or a new Image2D is bound as the background image, the modifications are immediately reflected
in the Background object.
The background image must be in RGB or RGBA format. Furthermore, it must be in the same format as the
currently bound rendering target. This is enforced by the render(World)75 and clear72 methods in
Graphics3D.
A cropping rectangle very similar to that of Sprite3D is available to facilitate scrolling and zooming of the
background image. The contents of the crop rectangle are scaled to fill the entire viewport. The crop rectangle
need not lie within the source image boundaries. If it does not, the source image is either considered to repeat
indefinitely in the image space (the REPEAT mode) or to not repeat at all, with pixels outside the source image
having the background color (the BORDER mode).
Contrary to texture images, the width and height of a background image do not have to be powers of two.
Furthermore, the maximum size of a background image is only determined by the amount of available memory;
there is no fixed limit. The dimensions of the crop rectangle are also unbounded.

Member Summary
Fields
static int BORDER41
static int REPEAT41
Constructors
Background()42

40
 javax.microedition.m3g Background
BORDER

Member Summary
Methods
int getColor()42
int getCropHeight()42
int getCropWidth()42
int getCropX()42
int getCropY()43
Image2D getImage()43
int getImageModeX()43
int getImageModeY()43
boolean isColorClearEnabled()43
boolean isDepthClearEnabled()43
void setColor(int ARGB)43
void setColorClearEnable(boolean enable)44
void setCrop(int cropX, int cropY, int width, int height)44
void setDepthClearEnable(boolean enable)44
void setImage(Image2D image)45
void setImageMode(int modeX, int modeY)45

Inherited Member Summary

Methods inherited from class Object
equals(Object), getClass(), hashCode(), notify(), notifyAll(), toString(), wait(),
wait(), wait()

Methods inherited from class Object3D138

addAnimationTrack(AnimationTrack)140, animate(int)141, duplicate()142, find(int)142,
getAnimationTrack(int)142, getAnimationTrackCount()143, getReferences(Object3D[])143,
getUserID()144, getUserObject()144, removeAnimationTrack(AnimationTrack)144,
setUserID(int)144, setUserObject(Object)145

Fields
BORDER
public static final int BORDER

Specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are
considered to have the background color.

REPEAT
public static final int REPEAT

Specifies that the imaginary pixels outside of the source image boundaries in X or Y direction are
considered to have the same color as the pixel in the corresponding position in the source image. Formally,
a pixel at position X will have the same color as the pixel at position X % N, where N is the width or height
of the image and % is the modulo operator.

41
Background javax.microedition.m3g
Background()

Constructors
Background()
public Background()

Constructs a new Background with default values. The default values are:
• color clear enable : true (clear the color buffer)
• depth clear enable : true (clear the depth buffer)
• background color : 0x00000000 (black, transparent)
• background image : null (use the background color only)
• background image mode : BORDER, BORDER
• crop rectangle : undefined (reset at setImage

Methods
getColor()
public int getColor()

Retrieves the current background color.

Returns: the current background color in 0xAARRGGBB format
See Also: setColor43

getCropHeight()
public int getCropHeight()

Gets the current cropping rectangle height within the source image.
Returns: the height of the cropping rectangle
See Also: setCrop44

getCropWidth()
public int getCropWidth()

Gets the current cropping rectangle width within the source image.
Returns: the width of the cropping rectangle
See Also: setCrop44

getCropX()
public int getCropX()

Retrieves the current cropping rectangle X offset relative to the source image top left corner.
Returns: the X offset of the cropping rectangle
See Also: setCrop44

42
Another Random Scribd Document
with Unrelated Content
He said he found you an ‘interesting young man.’”
“Did he? Confound his impudence!” That monocle-man certainly did
ruffle Bob.
“You forget he’s an old friend of my aunt’s.” Severely. “As I was
saying, Lord Stanfield found you ‘interesting,’ and we agreed there
might be a method,” studying him closely, “but when we came to
search for one, we couldn’t find it.”
She didn’t ask a question, so he didn’t have to reply.
“Mr. Bennett, why did you answer me like that down in the village?”
Bob hung his head. He felt worse than a boy detected stealing
apples. “Had to,” he muttered desperately.
“Why?” There was no mercy in that still pitiless voice.
Bob took another long breath. “Please don’t ask me,” he pleaded
after an ominous pause. That wasn’t not telling the truth; it was only
temporizing.
The violet eyes gleamed dangerously. “I’m just a little bit curious,”
said the girl in the same annihilating tone. “In the light of
subsequent proceedings, you will understand! And as Mrs. Ralston’s
niece! Aunt doesn’t quite realize things yet. The others have spared
her feelings. I haven’t, of course, gone to her. Aunt and I never ‘talk
over’ our guests.” Proudly.
That made Bob wince. He looked at her with quite helpless eyes.
“Maybe she will order me off the premises before long,” he said
eagerly. “I have already been considering the possibility of it. Believe
me,” earnestly, “it would be the best way. Can’t you see I’m—
dangerous—positively dangerous? I’m worse than a socialist—an
anarchist! Why, a Russian nihilist couldn’t make half the trouble in
the world that I can. I’m a regular walking disturber. Disaster follows
in my path.” Bitterly. “Some people look upon me as worse than the
black plague. Now if your aunt would only turn me out? You see I
can’t go unless she does. Got to think of that even-tenor-of-my-way!
But if she would only quietly intimate—or set the dog on me—”
The girl gazed at him more steadily. “I wonder if the judge and the
doctor and Mrs. Vanderpool aren’t right, after all?” she observed
slowly. “Let me look in your eyes, Mr. Bennett.” Bob did. Miss Gerald
had heard that one could always tell crazy people by their eyes. She
intended to sift this matter to the bottom and therefore proceeded
with characteristic directness. Folk that were—well, “off,” she had
been told, invariably showed that they were that, by a peculiar
glitter.
Miss Gerald gazed a few moments critically, steadily and with
unswerving intention. Bob withstood that look with mingled
wretchedness and rapture. He began to forget that they were just
the eyes of a would-be expert on a mental matter, and his own eyes,
looking deeper and deeper in those wonderful violet depths (he
stood so she got the benefit of the moonlight) began to gleam with
that old, old gleam Miss Gerald could remember in the past. Bob had
never talked love in those blissful days of yore, but he had looked it.
“I don’t see any signs of insanity,” said the girl at length with cold
assurance. That gleam wasn’t a glitter. Nothing crazy about it! She
had seen it too often in other men’s eyes, as well as in Bob’s—not
perhaps to such a marked degree in other men’s eyes,-but
sufficiently so that she was fairly familiar with it. “You look normal
enough to me.”
“Thank you,” said Bob gratefully.
“And that’s just why”—a slight frown on the smooth fine brow—“I
don’t understand. Of course, a man not normal, might have
answered as you did me (I’m not thinking of it as a personal matter,
you will understand).”
“Oh, I understand that,” returned Bob. “I’m just a problem, not a
person.” She made him quite realize that. She made it perfectly and
unmistakably apparent that he was, unto her, as some example in
trigonometry, or geometry, or algebra, and she wanted to find the
“solution.” He was an “X”—the unknown quantity. The expression on
her patrician features was entirely scholastic and calculating. Bob
now felt the ardor of his gaze becoming cold as moonlight. This
wasn’t a lovers’ bower; it was only a palestra, or an observatory.
“You haven’t answered me yet,” she said.
No diverting her from her purpose! She was certainly persistent.
“You insist I shall tell you why I didn’t want to see you?”
She looked at him quickly. “That isn’t what I asked, Mr. Bennett. I
asked you to explain that remark in the village.”
“Same thing!” he murmured. “And it’s rather hard to explain, but if
I’ve got to—?” He looked at her. On her face was the look of proud
unyielding insistence. “Of course, I’ve got to tell you the truth,” said
Bob, and his tone now was dead and dull. “In the first place, dad’s
busted, clean down and out, and—well, I thought I wouldn’t see you
any more.”
“I fail to see the connection.” Her tones were as metallic as a voice
like hers could make them.
“It’s like this!” said Bob, ruffling his hair. Here was a fine romantic
way to make an avowal. “You see I was in love with you,” he
observed, looking the other way and addressing one of the
furthermost stars of the heaven. “And—and—when a fellow’s in love
—and he can’t—ah!—well, you know—ask the girl—you
understand?”
“Very vaguely,” said Miss Gerald. Bob’s explanation, so far, was one
of those explanations that didn’t explain. If he had so heroically
made up his mind not to see her, he could have stayed away, of
course, from the Ralston house. He couldn’t explain how he was
bound to accept the invitation to come, on account of being in
“honor bound” to that confounded commodore, et al., to do so.
There were bound to be loose ends to his explanation. Besides,
those other awfully unpleasant things that had happened? He had to
tell the truth, but he couldn’t tell why he was telling the truth. That
had been the understanding.
Miss Gerald, at this point, began to display some of those alert and
analytical qualities of mind that had made her father one of the
great railroad men of his day. For an instant she had turned her
head slightly at Bob’s avowal—who shall say why? It may be she had
felt the blood rush swiftly to her face, but if so a moment later she
looked at him with that same icy calm. One hand had tightened on
the cold balustrade, but Bob hadn’t noticed that. She plied him now
with a number of questions. She kept him on the gridiron and while
he wriggled and twisted she stirred up the coals, displaying all the
ability of an expert stoker. He was supersensitive about seeing her
and yet as a free agent (she thought him that) he had seen her.
From her point of view, his mental processes were hopelessly
illogical—worse than that. Yet she knew he was possessed of a
tolerable mentality and a good-enough judgment for one who had in
his composition a slight touch of recklessness.
“I give it up,” she said at length wearily.
“Do you? Oh, thank you!” exclaimed Bob gratefully. “And if your aunt
orders me from the place—”
“But why can’t you just go, if you want to? I’m sure no one will
detain you.” Haughtily.
“Can’t explain, only it’s impossible. Like Prometheus bound to the
rock for vultures to peck at, unless—”
“How intelligible! And what a happy simile—under the
circumstances!” with far-reaching scorn. “What if I should tell my
aunt that her guest compared himself to—?”
“That’s the idea!” returned Bob enthusiastically. “Tell her that! Then,
by jove, she would—Promise me! Please!”
“Of course,” said the girl slowly, “my diagnosis must be wrong.” Or
perhaps she meant that she had lost faith in that glitter-theory.
“If you only could understand!” burst from Bob explosively. It was
nature calling out, protesting against such a weight of anguish.
But Miss Gerald did not respond. A statue could not have appeared
more unaffected and unsympathetic. She had half turned as if to go;
then she changed her mind and lingered. It annoyed her to feel she
had been baffled, for she was a young woman who liked to drive
right to the heart of things. Her father had been called a “czar” in his
world, and she had inherited, with other of his traits, certain
imperious qualities. So for a moment or two she stood thinking.
An automobile from the village went by them and proceeded to the
house. It contained Mrs. Dan and Mrs. Clarence returning from the
telegraph office, but Bob hardly saw it, or was aware who were its
occupants. Miss Gerald absorbed him to the exclusion of all else
now. He had no mind for other storms that might be gathering.
Suddenly the girl turned on him with abrupt swiftness.
 CHAPTER VIII—NEW COMPLICATIONS
“Is your father’s embarrassment serious?” she asked.
Bob looked startled. He didn’t like the way she had shifted the
conversation. “Pretty bad,” he answered.
“I believe, though, it’s customary for men on the ‘street’ not to stay
‘downed,’ as they say?”
“Don’t know as it’s an invariable rule,” returned Bob evasively. Then
realizing it wouldn’t do to be evasive: “As a matter of fact, I don’t
believe I’m very well posted as to that,” he added.
“What does your father say?” she asked abruptly.
Bob would much rather not have talked about that with her. But
—“Dad says there is no hope,” he had to say.
Miss Gerald was silent for a moment. As a child she remembered a
very gloomy period in her own father’s career—when the “street”
had him “cornered.” She remembered the funereal atmosphere of
the big old house—the depression on nearly every one’s face—how
everything had seemed permeated with impending tragedy. She
remembered how her father looked at her, a great gloomy ghost of
himself with somber burning eyes. She remembered how seared and
seamed his strong and massive face had become in but a few days.
But that was long ago and he had long since left her for good. The
vivid impression, however, of that gloomy period during her
childhood remained with her. It had always haunted her, though her
father had not been “downed” in the end. He had emerged from the
storm stronger than ever.
The girl shot a sidewise look at Bob, standing now with his arms
folded like Hamlet. Perhaps he had come from such a funereal house
as she, herself, so well remembered? Had dad’s trouble, or tragedy,
weighed on him unduly? Had it made him—for the moment—just
slightly irresponsible? Miss Gerald, as has been intimated, had
frankly liked Bob as an outdoor companion, or an indoor one, too,
sometimes, for that matter. He was one of the few men, for
example, she would “trot” with. He could “trot” in an eminently
respectful manner, being possessed of an innate refinement, or
chivalry, which certainly seemed good to her, after some of those
other wild Terpsichorean performances of myriad masculine manikins
in the mad world of Milliondom.
“I suppose your father has taken his trouble much to heart?” Miss
Gerald now observed.
“Not a bit.”
“No?” In surprise.
“No.”
“Why not?”
“Said he looked to me to keep him in affluence the rest of his days.”
“To you?”
“That’s right.”
“But how?—What are you going to do?”
“Hustle.”
“At what?”
“Don’t know. Got to find out.”
“What did you plan doing, when at college?”
“Nothing.”
“Is it”—Miss Gerald got back to where she had been before—“the
sense of awful responsibility,” with slight sarcasm, “that has turned
your brain?”
“I’m not crazy.”
“No?” She remembered that most people in asylums say that.
“Though I may be in a matter of three weeks,” Bob added, more to
himself than to her.
“Why three weeks?”
“Well, if I don’t—just shouldn’t happen to go crazy during that time,
I’ll be all right, after that.”
“Why do you allow a specified period for your mental deterioration?”
“I didn’t allow it.”
“Who did?”
“Can’t tell you.”
Miss Gerald pondered on this answer. It would seem as if Bob had
“hallucinations,” if nothing worse. He was possessed of the idea, no
doubt, that he would go crazy within three weeks. He didn’t realize
that the “deterioration,” she referred to, might have already begun.
He looked normal enough, though, had the most normal-looking
eyes. Could it be that he was acting? And if he was acting, why was
he? That seemed incomprehensible. Anyhow, it couldn’t be a sense
of responsibility that had “upset” Bob. She became sure of that now.
He played a losing game with too much dash and brilliancy! Hadn’t
she seen him at polo—hadn’t she held her breath and thrilled when
he had “sailed in” and with irresistible vim snatched victory out of
defeat? No; Bob wasn’t a “quitter.”
“So your father looks to you to support him?”
“So he said. The governor’s a bit of a joker though, you know. He
may be only putting up a bluff to try me out.”
“What did he advise you to do?”
Bob shivered. “Matrimonial market.”
“You mean—?”
“Heiress.” Succinctly.
“Any particular one?”
“Dad did mention a name.”
“Not—?” She looked at him.
“Yes.”
An awful pause.
“Now you know why I didn’t want to see you,” said Bob, in that even
fatalistic voice. “First place, I wouldn’t ask you to marry me, if you
were the last girl in the world! Second place, I was afraid if I saw
you, some of these things dad said to try me, would be bound to
pop out. You mustn’t think badly of dad, Miss Gerald. As I’ve said, he
didn’t mean a word of it. He was only sizing me up. Don’t I know
that twinkle in his eye? Just wanted to see if I’m as lazy and good-
for-nothing as some chaps brought up with the silver spoon. Why,
he’d—honestly, dad would just kick me, if I took his advice. Why, if I
went back home to-morrow,” went on Bob, warming to the subject,
“and told him we were engaged”—the girl moved slightly—“and
were going to be married right off”—the girl moved again—“why—
why, old as I am, dad would take off his coat and give me a good
trouncing. That’s the kind of a man dad is. I see it all now.”
He really believed he did—and for the first time. He felt he had
solved the mystery of dad’s manner and conduct. It had been a
mystery, but the solution had come to him like an inspiration. Dad
wanted to see whether he would arise to the occasion. He had told
him he didn’t believe he was worth his salt just to see his backbone
stiffen. He had alluded to that other way of repairing the “busted
family credit” just to observe the effect on Bob. And how dad must
have chuckled inwardly at Bob’s response! Why, they’d almost had a
scene, he and good old dad. Bob could smile at it now—if he could
smile at anything. He certainly had been a numskull. Dad, pulling in
fish somewhere, was probably still chuckling to himself, and
wondering how Bob would work out the problem.
“Dad was always just like that when I was a boy,” he confided to
Miss Gerald, now standing more than ever like a marble lady in the
moonlight. “He would propose the contrariest things! Always trying
and testing me. Guess that’s why he acted so happy when he went
broke. Thought it would make a man of me! By jove, that’s it! Why,
he was as care-free as a boy with a new top!”
“Was he, indeed?” said Miss Gerald, studying Mr. Robert Bennett
with eyes that looked very deep now, beneath the imperious brows.
“How nice!” Oh, that tone was distant. It might have been wafted
from one who stood on an iceberg.
“Isn’t it?” Bob heaved a sigh. “I’m not afraid of you any more,” he
said, “now that I’ve got that off my chest.”
Again Miss Gerald shivered slightly, but whether at the slang or not,
was not apparent.
“You can’t frighten me any more,” said Bob.
“But why,” said Miss Gerald, “did you tell me, at all, of dad’s—as you
call him—charming suggestion?”
“Had to. Didn’t you ask me?” In faint surprise. Then he remembered
she didn’t know he had to tell the truth. That made him look rather
foolish—or “imbecile,” in the light of all those other proceedings.
Miss Gerald’s brow contracted once more. Again she might be asking
herself if Master Robert was acting? Was this but gigantic,
bombastic, Quixotic “posing” after all? It was too extraordinary to
speak of such things as he had spoken of, to her! Did he only want
to appear different? Did he seek to combine Apollo with Bernard
Shaw in his attitude toward society? Or had he been reading
Chesterton and was he but striving to present in his own personality
a futurist’s effect of upside-downness? Miss Gerald felt now the way
she had at the modernists’ exhibition, when she had gazed and
gazed at what was apparently a load of wood falling down-stairs,
and some one had told her to find the lady. It was about as difficult
to-night to find the real Mr. Bennett—the happy-go-lucky Bob
Bennett of last month or last week—as it had been to find that lady
where appeared only chaotic kindling wood.
Miss Gerald let the cool air fan her brow for a few moments. This
young man was, at least, exhilarating. She felt a little dizzy.
Meanwhile Bob looked at her with that sad silly smile.
“You can’t ask me any questions that will disconcert me now,” he
boasted.
Miss Gerald looked at him squarely. “Will you marry me?” she said.
It was a coup. Her father had been capable of just such coups as
that. He would hit the enemy in the most unexpected manner in the
most unexpected quarter, and thus overwhelm his foes. Miss Gerald
might not mean it; she, most likely, only said it. Under the
circumstances, to get at the truth herself, she was justified in saying
almost anything. If he were but posing, she would prick the bubble
of his pretense. If those grandiloquent, and, to her, totally
unnecessary protestations didn’t mean anything, she wished to know
it. He would never, never marry her,—wouldn’t he? Or, possibly, her
question was but part of a plan, or general campaign, on her part, to
test his sanity? Six persons—real competents, too!—had affirmed
that he wasn’t “just right.” Be that as it may, Miss Gerald dropped
this bomb in Master Bob’s camp and waited the effect with mien
serene.
Her query worked the expected havoc, all right. Bob’s jaw fell. Then
his eyes began to flash with a new fierce love-light. He couldn’t help
it. Marry her?—Great Scott!—She, asking him, if he would? He felt
his pulses beating faster and the blood pumping in his veins. His
arms went out—very eager, strong, primitive arms they looked—that
cave-man kind! Arms that seize resistless maidens and enfold them,
willy-nilly! Miss Gerald really should have felt much alarmed,
especially as there was so much doubt as to Bob’s sanity. It’s bad
enough to be alone with an ordinary crazy man, but a crazy man
who is in love with one? That is calculated to be a rather unusual
and thrilling experience.
However, though Miss Gerald may have entertained a few secret
fears and possible regrets for her own somewhat mad precipitancy,
she managed to maintain a fair semblance of composure. She had
the courage to “stand by” the coup. She was like a tall lily that
seems to hold itself unafraid before the breaking of the tempest. She
did not even draw back, though she threw her head back slightly.
And in her eyes was a challenge. Not a love challenge, though Bob
could not discern that! His own gaze was too blurred.
Miss Gerald suddenly drew in her breath quickly, as one who felt she
would need her courage now. Almost had Bob, in that moment of
forgetfulness, drawn her into his arms and so completed the
paradoxical picture of himself, when the impulse was abruptly
arrested. He seemed suddenly to awaken to a saner comprehension
of the requirements of the moment. His arms fell to his side.
“That’s a joke, of course,” he said hoarsely.
“And if it wasn’t?” she challenged him. There was mockery now in
her eyes, and her figure had relaxed.
“You affirm it isn’t?”
“I said if it wasn’t?”
“I guess you win,” said Bob wearily. These extremes of emotion were
wearing on the system.
“You mean you wouldn’t, even if I had really, actually—?”
“I mean you certainly do know how to ‘even up’ with a chap. When
he doesn’t dare dream of heaven, you suddenly pretend to fling
open the golden gates and invite him to enter.”
“Like St. Peter,” said the girl.
“Ah, you are laughing,” said Bob bitterly, and dropped his head. Her
assurance was regal. “As if it wasn’t hard enough, anyway, to get
you out of my darn-fool head,” he murmured reproachfully.
“Then you reject me?” said the girl, moving toward the entrance.
“Good! I mean, bad! So humiliating to have been rejected! Good
night, Mr. Bennett. No—it isn’t necessary for you to accompany me
to the house. I really couldn’t think of troubling you after your
unkind refusal to—”
Bob groaned. “I say, there is always your aunt, you know, who can
ask me to vacate the—” he called out.
“I’ll think about it,” said the lady. A faint perfume was wafted past
him and the vision vanished. Bob sank down on the cold marble
seat.

He remained thus for some time, oblivious to the world, when

another car, en route from the village to the house, purred past him,
spitting viciously, however, between purrs. Bob didn’t even look
around. Spit!—spit!—purr!—purr!—Its two lights were like the eyes
of some monster pussy-cat, on the war-path for trouble. Spit!—it
seemed in a horribly vicious mood. More “spits” than “purrs,” now!
Then the car stopped, though it was some distance from the house.
“Curse this old rattletrap!” said a man’s voice.
“Oh, I guess no one’ll pay any attention to it,” spoke another
occupant. “Besides, it was the only one to be had at the station, and
we had to get here quick.”
“You bet! The quicker, the better,” observed a third man.
They all got out, not far from where Bob sat in the dark gazing into
a void, but he did not notice. Cars might come, and cars might go,
for all of him. He was dimly aware of the sound of voices but he had
no interest in guests, newly-arrived or otherwise. One of the trio
paid the driver of the car and it purred back, somewhat less
viciously, from whence it came.
“Better separate when we get near the house and approach it
carefully,” said the first speaker in low tense tones. “We’ve got to get
hold of him without anybody knowing it.”
“That’s right. Wouldn’t do to let them”—with significant accent
—“know what we’ve come for,” said the second man. The trio were
quite out of ear-shot of Bob, by now.
“Hope it’ll turn out all right,” spoke the third anxiously. “Why, in
heaven’s name, didn’t we think of this in the first place?”
“Can’t think of every contingency!” answered the first speaker
viciously. “Our plan now is to get hold of one of the servants. A nice
fat tip, and then—Come on! No time to waste!”
As they made their way up the driveway to the house Bob looked
drearily around. His eyes noted and mechanically followed the trio of
dark forms. He saw them stop near the house; then he observed
one approach a side window and peer in. A moment later another
approached another window and peered in.
“That’s funny!” thought Bob, without any particular emotion. At the
same time, he recalled that a band of burglars had been going
about, looting country-houses. Perhaps these fellows were after a
few hundred thousand dollars’ worth of jewels? There might be half
a million dollars’ worth of jewelry sprinkled about among Mrs.
Ralston’s guests. But what did it matter? The presence of these
intruders seemed too trifling a matter to think about now, and Bob
sank into another reverie.
How long he remained thus, he did not know. The laughter and talk
of a number of guests, coming out the front way (end of a “trot,”
probably) aroused him and Bob got up.
As he did so, he fancied he saw again the three men he had noticed,
then forgotten, slip around toward the back of the house.
Throughout the gardens, the moonlight made clear spots on the
ground where the bright rays sifted through the foliage or shone
down between the trees, and they had to skip across one of these
bright places to get around somewhere behind the big mansion.
Undoubtedly, the appearance from the house of the guests who
wanted to cool off had startled the intruders and inspired a desire to
make themselves less conspicuous for the time being. Bob
entertained a vague impression that the conduct of the trio was
rather crude and amateurish, though that didn’t worry him. He didn’t
care whether they were full-fledged yeggmen of the smoothest
class, or only bungling artists, a discredit to their profession. He
dismissed consideration of them as quickly again as he had done
before.
A yawn escaped his lips, and it rather surprised him that a broken-
hearted man could yawn. He looked at his watch, holding it in the
moonlight, and saw that it was late enough now so that he could
retire if he wished, without violating, to any great degree, that even-
tenor-of-his-way clause. Accordingly Bob got up and walked toward
the house. A side door was open and he went in that way and up to
his room. He was glad he didn’t encounter any one—that is, any one
he had to speak to. The monocle-man drifted by him somewhere,
but Bob didn’t have to pay much attention to him. He could imagine
the superior way in which the Britisher had informed Miss Gerald
that he found him (Bob) an “interesting young man.” The monocle-
man and the bishop seemed to agree on that point.
Undressing hastily, Bob flung himself into bed. He had gone through
so much he was tired and scarcely had he touched the sheets when
the welcoming arms of Morpheus claimed him. His sleep was sound
—very sound! In fact, it was so sound that something occurred and
he didn’t know it. It occurred again—several times—and still he did
not know it. Another interval!—a long one! Bob yet slept the sleep of
the overwrought. His fagged brain was trying to readjust itself. He
could have slept right through to the dawn, but this was not to be.
Long before the glowing god made its appearance in the east, Bob
was rudely yanked from the arms of Morpheus.
 CHAPTER IX—ANOTHER SURPRISE
Three men were in his room and Bob found himself sitting up in bed
and blinking at them. The lights they had turned on seemed rather
bright.
“Hello!” said Bob.
“Hello yourself!” said the commodore in a low but nasty manner.
“And not so loud!”
“Some sleeper, you are!” spoke Dickie in a savage whisper.
“Believe he heard, all right!” came Clarence’s hushed, unamiable
tones. “Perverse beast, and pretended not to!”
Bob hugged his knees with his arms. “You’ve torn your pants,” he
observed to the commodore.
“Never you mind that” as guardedly, though no more pleasantly than
before.
“Oh, all right,” said Bob meekly. He didn’t ask any questions, nor did
he exhibit any curiosity. There couldn’t anything happen now that
would make matters much worse. But in that, he was “reckoning
without his host.”
“Got in the window, of course,” he observed in a low unconcerned
tone, as if their coming and being there after midnight was the most
natural occurrence in the world. “Not so hard to get in, with that
balcony out there. All you had to do was to ‘shin up’ and then there’s
that trellis to help. Good strong trellis, too. Regular Jacob’s ladder!
Easiest thing for burglars! Thought you were burglars,” he added
contemplatively.
“You mean you saw us?” snapped the commodore, almost forgetting
his caution. His expression matched his tone. He was no longer the
jovial sailorman; he wore now a regular Dick Deadeye look. To Bob’s
comprehensive glance he appeared like a fragment in a revival of
Pinafore.
“Oh, I didn’t know it was you,” said Bob.
“Where were you?”
“Summer-house.”
“Think of that,” murmured the commodore, disgustedly. “Bird at
hand, and we didn’t know it. Fool of a bird had to hop away and
make us all this trouble!”
“I told you I thought you were burglars,” observed Bob patiently. He
didn’t care how they abused him or what names they called him.
That disagreeable look on Dan’s face was replaced by a startled one.
“Good gracious, man”—only that wasn’t the expression he used—“I
hope you haven’t told any one you saw burglars prowling around?
Nice for us if you did!” As he spoke he gazed anxiously toward the
window, before which they had taken the precaution to draw a
heavy drape after entering.
“No, I didn’t tell a soul.”
“But—I don’t understand why you didn’t when you thought—?”
“I ought to have spoken, I suppose,” said Bob with a melancholy
smile. “But it didn’t seem very important and—I guess I forgot.
These little jewel robberies are getting to be such commonplace
occurrences!”
The commodore stared at him. Then he touched his forehead. “A lot
of trouble you’ve made for us,” he said, speaking in that low tense
voice, while Clarence and Dickie looked on in mad and reproachful
fashion. “Bribed a servant to tell you to slip out! Told him to whisper
that we were waiting in the garden and simply had to see you at
once! Didn’t you hear him rap on your door?”
“No,” answered Bob sorrowfully.
“Heavens, man! believe you’d sleep through an earthquake and
cyclone combined! Servant came back and told us he’d tapped on
your door as loudly as he dared. Was afraid he’d arouse the whole
house if he knocked louder. When you leave a ‘call’ at the hotels,
how do they manage? Break down the door with an ax?”
Bob overlooked the sarcasm. The commodore might have thumped
him with an ax, at the moment, and he wouldn’t have protested very
hard. He murmured a contrite apology.
“Get my telegram?” said the commodore.
“Yes. What could you have been thinking about when you sent it?
How could I leave when I had to stay? Thought you must have been
sailing pretty close in the wind at the yacht club, when you dashed it
off! Could just feel your main-sail fluttering.”
The commodore swore softly but effectively. Clarence and Dickie
murmured something, too. Bob hugged his knees closer. Being so
unhappy himself, he couldn’t but feel a dull sympathy when he saw
any one else put out.
“See here,” said the commodore, “what’s the situation? We never
dreamed, of course, that you would come here. Have you been
talking with Mrs. Dan and Mrs. Clarence? Dickie’s been conjuring all
kinds of awful things you might have told them, if they cornered you
and you got that truth-telling stunt going. Dickie’s got an
imagination. Too confounded much imagination!” Here the
commodore wiped his brow. That was quite a bad tear in his pants
but he appeared oblivious to it. “Maybe you would have thought it a
capital way to turn the tables on us poor chaps?” he went on,
stabbing Bob with a baleful look. “Perhaps you came here on
purpose?”
“No,” said Bob, “I couldn’t have done that, of course, owing to the
conditions.” And he related what had happened to bring him there.
Dan groaned. “Why, it was we, ourselves, who steered him right up
against her at the Waldorf. It was we who got him asked down here.
I suppose you’ve been chuckling ever since you came?” Turning on
Bob, with a correct imitation of Mr. Deadeye, at his grouchiest
moment.
“No,” said Bob, speaking to immeasurable distance, “I haven’t done
any chuckling since I came here. Nary a chuckle!”
“Let’s get down to brass tacks,” interrupted Dickie, “and learn if our
worst apprehensions are realized. There’s a girl down here I think a
lot of and I’d like to know if, by any chance, any conversation you
may have had with her turned on me. I allude to Miss Dolly—”
“Hold on,” said the commodore. “That’s not very important. Suppose
she should have found out a few things about you? You aren’t
married. It’s different in the case of married men, like Clarence and
me here. We’ll dismiss Miss Dolly, if you please, for the present—”
“I really haven’t said anything to Miss Dolly about you,” said Bob to
Dickie. “Your name hasn’t been mentioned between us.” He was glad
he could reassure one of them, at least. He wouldn’t have had Dickie
so sorrowful as himself for the world.
That young man looked immensely relieved. It may be he
experienced new hope of leading the temperamental young thing to
the altar, and incidentally consummating a consolidation of
competing chimneys, conveniently contiguous. “Thanks, old chap,”
he said, and shook Bob’s hand heartily.
“But what about us?” whispered the commodore sibilantly. “Have
you talked with Mrs. Clarence or Mrs. Dan to any great extent?”
“I haven’t had hardly a word with Mrs. Clarence,” answered Bob,
whereupon Clarence began to “throw out his chest,” the way Dickie
had done.
The commodore shifted uneasily, seeming to find difficulty in
continuing the conversation. He moved back and forth once or twice,
but realizing he was making a slight noise, stood still again, and
looked down at Bob.
“Talk much with Mrs. Dan?” he at length asked nervously.
“I did have a little conversation with Mrs. Dan,” Bob was forced to
reply. “Or, I should say, to be strictly truthful, rather a long
conversation. You see, I took her in to dinner.”
The commodore showed signs of weakness. He seemed to have very
indecisive legs all of a sudden. “Talk about me?” he managed to
ejaculate.
“Some. I’m not certain just how much.”
“What—what was said?”
“I can’t remember all. It’s very confused. I’ve had a lot of
conversations, you see, and most of them awfully unpleasant. I
remember, though, that Mrs. Dan impressed me as a very broad-
minded lady. Said she had lived in Paris, and was not a bit jealous.”
“What!” Dan was breathing hard.
“Said she always wanted you to have the best kind of a time.”
“Did she say that?” asked the commodore. “And you believed it? Go
on.” In a choked voice. “Did you tell her about that cabaret
evening?”
“I believe it was mentioned, incidentally.”
“Say I was there?” put in Clarence quickly. He was losing that
“chestiness.”
“I rather think I did. I—what is that?” Bob looked toward the
window. There was a sound below at the foot of the balcony. Some
one turned out the light in the room and Bob strode to the window
and looked out. “It’s a dog,” he said. “He’s snuffing around at the
foot.”
“He’s doing more than snuffing,” observed the commodore
apprehensively, as at that moment a bark smote the air. They stood
motionless and silent. The dog stopped barking, but went on
snuffing. Maybe it would go away after a moment, and they waited.
Dickie and the commodore had thrashed out that question of dogs.
With so many guests around, they had figured that, of course, they
would be dog-safe. Didn’t they look like guests? How could a dog tell
the difference between them and a guest? It is true, they hadn’t
been expecting so much trouble as they had been put to, to find
Bob. They had, in that little balcony-climbing feat, rather exceeded
what they had expected to be called on to do. In their impatience,
they had acted somewhat impetuously, but it had looked just as
easy, after the servant had pointed out the room and told them Bob
was in, as certain sounds from his bed indubitably indicated.
They couldn’t very well enter the house as self-invited guests,
though they, of course, would have been made welcome. They
couldn’t very well say they had all changed their minds about those
original invitations which had naturally included husbands as well as
wives. After all three had declined to come on account of business, it
would certainly look like collusion, if all three found they hadn’t had
urgent business, at all, in town. If anything untoward or disastrous
had happened in the conversational line, with Bob as the Demon
God, Truth, their sudden entrance upon the stage of festivities,
would seem to partake of inner perturbation; it might even appear
to be a united and concentrated case of triple guilty conscience.
This, obviously, must be avoided at any cost. How they had heard
Bob was here at the Ralston house, matters not. Naturally they had
kept tab on his movements, where he went and what he did being
of some moment to them.
The dog barked again. Thereupon, a window opened and they knew
that some one had been aroused.
“He’s looking out. It’s the monocle-chap,” whispered Bob.
“Who’s he?”
“One of Mrs. Ralston’s importations. Belonged to that Anglo-English
colony when she did that little emigration act in dear old London.”
“Hang it, we’ve got to get out,” whispered the commodore nervously.
No matter what had been said; no matter what the Demon God of
Truth had done, it was incumbent on them not to remain longer,
with that dog looking up toward Bob’s window and making that
spasmodic racket. Some one might get up and go out and see
footprints, or a disturbed trellis. The commodore forgot a certain
desperate business proposition, apropos of that confounded wager,
he had come to put to Bob. That infernal dog got on his nerves and
put that other matter, which would settle this truth-telling stunt at
once, right out of his mind.
It was all very well, however, to say they “had to get out,” but it was
another matter to tell how they were going to do it. They couldn’t
descend the way they had come, and meet doggie. Bob arose to the
occasion.
“I can let you into the hall and show you downstairs, to that side
door on the other side of the house. You can take one of my golf
sticks, just as a safeguard, but I think you’ll be able to circumvent
the jolly little barker without being obliged to use it.”
“What kind of a dog is it?” whispered the commodore who had a
pronounced aversion to canines.
“Looked like a smallish dog. Might be a bull.”
“Better give us each a club,” suggested Clarence in a weak voice.
Which Bob did. The dog renewed the vocal performance, and—
“Hurry,” whispered the commodore. “Find means to communicate
with you to-morrow, Mr. Bennett.” Bob didn’t resent the formality of
this designation, which implied to what depths he had fallen in good
old Dan’s estimation. “Can we get down-stairs without any one
hearing us?”
Bob thought they could. Anyhow, they would have to try, so he
opened the door softly and led the way. Fortunately, the house was
solidly built and not creaky. They attained down-stairs safely, and at
last reached the side door without causing any disturbance. Bob
unfastened the door, the key turned noiselessly and they looked out.
There was no sign of any living thing on lawn or garden on this side
of the house.
“Out you go quickly,” murmured Bob, glancing apprehensively over
his shoulder. His position was not a particularly agreeable one.
Suppose one of the servants, on an investigating tour as to the
cause of doggie’s perturbation, should chance upon him (Bob)
showing three men out of the house in that secret manner at this
time of night?
But before disappearing into the night, the commodore took time to
whisper: “Was Gee-gee’s name mentioned?”
“I fear so,” said Bob sadly.
The commodore wasted another second or two to tell Bob fiercely
what he thought of him and how they would “fix” him on the
morrow, after which he sprang out and darted away like a rabbit.
Bob wanted to call out that they were welcome to “fix” him, but he
was afraid that others beside Dan might hear him, so he closed and
locked the door carefully and stood there alone in the great hall, in
his dressing-gown. Then he sat down in a dark corner and listened.
Better wait until all was quiet, he told himself, before retracing his
steps to his room. The dog seemed to have stopped barking
altogether now and soon any persons it might have awakened would
be asleep again. His trio of visitors must be well on their way to the
village by this time, he thought. He was sorry the commodore
seemed to feel so bad. And Clarence?—poor Clarence! That last look
of his haunted Bob. Anyhow, he was pleased Dickie had, so far,
escaped his (Bob’s) devastating touch.
How long he sat there he did not know. Probably only a few
moments. A big clock ticked near by, which was the only sound now
to be heard. Suddenly it occurred to him that he had better return to
his room, and wearily he arose. Up-stairs it seemed darker than it
had been when he had left his room. He had the dim lights in the
great hall below to guide him then. Now it was a little more difficult.
However, after traversing without mishap a few gloomy corridors—
he realized what a big house it really was—he reached, at last, his
room near the end of one of the upper halls and entered.
He had a vague idea he had left his door partly ajar, but he wasn’t
sure; probably he hadn’t, for it was now closed; or maybe a draft of
air had closed it. Groping his way in the dark for his bed, he ran
against a chair. This ruffled his temper somewhat as the sharp edge
had come in contact with that sensitive part of the anatomy, known
as the shin-bone. He felt for his bed, but it wasn’t there where it
ought to be. He must have got turned around coming in. His fingers
ran over a dresser. Some of the articles on it seemed strange to him.
He thought he heard a rustle and stood still, with senses alert,
experiencing a regular burglar-feeling at the moment. He hadn’t
become so ossified to emotion as he had supposed. But everything
was now as silent as the grave. Again his hand swept out, to learn
where he was, and again his fingers swept over the dresser. What
were all those confounded things? He didn’t know he had left so
much loose junk lying around. And where was that confounded
switch-button?
At that moment some one else found it, for the room became
suddenly flooded with light. Bob started back, and as he did so,
something fell from the dresser to the floor. He stared toward the
bed in amazement and horror. Some one, with the clothes drawn up
about her, was sitting up. Bob wasn’t the only one who had a
surprise that night. The temperamental, little dark thing was treated
to one, too. Above the white counterpane, she stared at Bob.
 CHAPTER X—INTO BONDAGE
She continued to stare for some moments, while he stood frozen to
the spot. Then the young lady’s face changed. Fear, startled wonder,
gave way to an expression of growing comprehension and into her
eyes came such an excited look.
“You!” said Miss Dolly in a thrilling whisper. And then—“Pick it up,
please.”
Instead of picking anything up—he didn’t know what—Bob was
about to rush for the door, when— “Stop! Or I’ll scream,” exclaimed
Miss Dolly. “I’ll scream so loud I’ll wake every one in the house.”
Bob stopped. In his eyes was an agony of contrition and shame.
Miss Dolly, however, seemed quite self-possessed. She might have
been frightened at first, but she was no longer that. Her
temperamental, somewhat childish face wore a thrill of pleasurable
anticipation. “Now pick it up,” she repeated.
“What?” stammered Bob in a shrinking voice.
“The brooch, to be sure. Didn’t you drop it?”
“I?” said Bob, drawing his dressing-gown closer about him. They
were speaking in stage whispers.
“Of course. Wasn’t it what you came for?”
“Came for? Great heavens!—Do you think?—”
“Think?” said Miss Dolly. “I know.”
Bob looked at her. Her face appeared elf-like, uncannily wise. But for
all her outward calm, her eyes were great big, excited eyes. His
horrified glance turned quickly from them to regard a gleaming
diamond and pearl brooch on the rug. “Jumping Je-hoshaphat! You
don’t think I’m—”
“One of those thrilling society-highwaymen, or social buccaneers?”
said Miss Dolly. “Of course, and I’m so glad it happened like this. I
wouldn’t have missed it for the world. Really, I’ve always wanted to
meet one of those popular heroes. And now to think my dream has
come true! It’s just like a play, isn’t it?”
“It is not,” replied Bob savagely. This was too much. It was just
about the last straw. “I—” Then he stopped. Suppose any one
should hear him? Miss Dolly’s temperamental and comprehensive
eyes read his thought.
“I don’t think there’s any danger,” she purred soothingly. “You see
there’s a bathroom on one side of the room and a brick wall on the
other. I wouldn’t be surprised if all the rooms are separated by brick
partitions,” she confided to him. “Mrs. Ralston likes everything
perfect—sound-proof, fire-proof, and all that.”
“See here,” said Bob. “I was just wandering around—couldn’t sleep—
and—and I came in here, quite by mistake. Thought it was my own
room!” With some vehemence.
Miss Dolly shook her head reprovingly, and her temperamental hair
flowed all about her over the white counterpane. She knew it must
look very becoming, it was such wonderful hair—that is, for dark
hair. Bob preferred light. Not that he was thinking of hair, now!
“Can’t you do better than that?” asked the temperamental young
thing.
“Better than what?” queried Bob ill-naturedly. He was beginning to
feel real snappy.
“Invent a better whopper, I mean?”
“It isn’t a whopper, and—and I positively refuse to stay here any
longer. Positively!”
“Oh, no; not positively,” said Miss Dolly, nodding a wise young head.
“You’re going to stay, unless—you know the alternative. Since I’m
destined to be a heroine, I want a regular play-scene. I don’t want
my part cut down to nothing. Don’t you love thief-plays, Mr.
Welcome to our website – the perfect destination for book lovers and
knowledge seekers. We believe that every book holds a new world,
offering opportunities for learning, discovery, and personal growth.
That’s why we are dedicated to bringing you a diverse collection of
books, ranging from classic literature and specialized publications to
self-development guides and children's books.

More than just a book-buying platform, we strive to be a bridge

connecting you with timeless cultural and intellectual values. With an
elegant, user-friendly interface and a smart search system, you can
quickly find the books that best suit your interests. Additionally,
our special promotions and home delivery services help you save time
and fully enjoy the joy of reading.

Join us on a journey of knowledge exploration, passion nurturing, and

personal growth every day!

ebookbell.com