My favorites | English | Sign in

o3d.Pack Class Reference

Inherits o3d.NamedObject

List of all members.


Detailed Description

A Pack object functions as a container for O3D objects. The Pack is used to control the lifetime scope of a collection of objects in bulk. The Pack object achieves this by simply storing a set of references to its contained objects, which ensures that the ref-counts for those objects never reach zero while the pack is alive.

See Also

Public Member Functions

!o3d.ArchiveRequest  createArchiveRequest() o3d.Pack
!Array.<!o3d.Bitmap createBitmapsFromRawData(rawData) o3d.Pack
o3d.RenderDepthStencilSurface  createDepthStencilSurface(width, height) o3d.Pack
o3d.FileRequest  createFileRequest(type) o3d.Pack
o3d.ObjectBase  createObject(typeName) o3d.Pack
!o3d.RawData  createRawDataFromDataURL(dataUrl) o3d.Pack
o3d.Texture2D  createTexture2D(width, height, format, levels, enableRenderSurfaces) o3d.Pack
o3d.TextureCUBE  createTextureCUBE(edgeLength, format, levels, enableRenderSurfaces) o3d.Pack
o3d.Texture  createTextureFromRawData(rawData, generateMips) [**DEPRECATED**] o3d.Pack
destroy() o3d.Pack
!Array.<!o3d.ObjectBase getObjects(name, classTypeName) o3d.Pack
!Array.<!o3d.ObjectBase getObjectsByClassName(classTypeName) o3d.Pack
boolean  isAClassName(className) o3d.ObjectBase
boolean  removeObject(object) o3d.Pack

Public Properties

string className o3d.ObjectBase
number clientId o3d.ObjectBase
string name o3d.NamedObject
!Array.<!o3d.ObjectBase> objects o3d.Pack

Member Function Documentation

Pack.createArchiveRequest ( )

Creates an ArchiveRequest so we can stream in assets from an archive

Returns:
!o3d.ArchiveRequest.an ArchiveRequest
!Array.<!o3d.Bitmap> Pack.createBitmapsFromRawData ( !o3d.RawData rawData )

Create Bitmaps from RawData. If you load a cube map you'll get 6 an array of 6 Bitmaps. If you load a volume map you'll get an array of n Bitmaps. If there is an error you'll get an empty array.

Parameters:
rawData contains the bitmap data in a supported format.
Returns:
!Array.<!o3d.Bitmap>.An Array of Bitmaps object.
o3d.RenderDepthStencilSurface Pack.createDepthStencilSurface ( number width
number height )

Creates a new RenderDepthStencilSurface object of a format suitable for use as a depth-stencil render target. Note: The dimensions of the RenderDepthStencilSurface must be a power of two.

Parameters:
width The width of the RenderSurface in pixels
height The height of the RenderSurface in pixels
Returns:
o3d.RenderDepthStencilSurface.The RenderSurface object.
o3d.FileRequest Pack.createFileRequest ( string type )

Creates a FileRequest to be used to asynchronously load a Texture or RawData. Note: Loading a "TEXTURE" is deprecated. The recommended way to load a texture is to load a RawData, use that to create Bitmap, Massage the Bitmap to your liking the use that to create a Texture.

Parameters:
type Must be "TEXTURE" or "RAWDATA"
Returns:
o3d.FileRequest.a FileRequest
o3d.ObjectBase Pack.createObject ( string typeName )

Creates an Object by Class name. Note: You may omit the 'o3d.'.

Parameters:
typeName name of Class to create. Valid type names are:
  • o3d.Bitmap
  • o3d.Canvas
  • o3d.CanvasLinearGradient
  • o3d.CanvasPaint
  • o3d.ClearBuffer
  • o3d.Counter
  • o3d.Curve
  • o3d.DrawContext
  • o3d.DrawElement
  • o3d.DrawList
  • o3d.DrawPass
  • o3d.Effect
  • o3d.FunctionEval
  • o3d.IndexBuffer
  • o3d.Material
  • o3d.ParamArray
  • o3d.ParamObject
  • o3d.Primitive
  • o3d.RenderFrameCounter
  • o3d.RenderNode
  • o3d.RenderSurfaceSet
  • o3d.Sampler
  • o3d.SecondCounter
  • o3d.Shape
  • o3d.Skin
  • o3d.SkinEval
  • o3d.SourceBuffer
  • o3d.State
  • o3d.StateSet
  • o3d.StreamBank
  • o3d.Texture2D
  • o3d.TextureCUBE
  • o3d.TickCounter
  • o3d.Transform
  • o3d.TreeTraversal
  • o3d.VertexBuffer
  • o3d.Viewport
  • o3d.Matrix4AxisRotation
  • o3d.Matrix4Composition
  • o3d.Matrix4Scale
  • o3d.Matrix4Translation
  • o3d.ParamOp2FloatsToFloat2
  • o3d.ParamOp3FloatsToFloat3
  • o3d.ParamOp4FloatsToFloat4
  • o3d.ParamOp16FloatsToMatrix4
  • o3d.TRSToMatrix4
  • Returns:
    o3d.ObjectBase.The created object.
    !o3d.RawData Pack.createRawDataFromDataURL ( string dataUrl )

    Create RawData given a data URL.

    Parameters:
    dataUrl The data URL from which to create the RawData.
    Returns:
    !o3d.RawData.The RawData.
    o3d.Texture2D Pack.createTexture2D ( number width
    number height
    o3d.Texture.Format format
    number levels
    boolean enableRenderSurfaces )

    Creates a new Texture2D object of the specified size and format and reserves the necessary resources for it. Note: If enable_render_surfaces is true, then the dimensions must be a power of two.

    Parameters:
    width The width of the texture area in texels (max = 2048)
    height The height of the texture area in texels (max = 2048)
    format The memory format of each texel
    levels The number of mipmap levels. Use zero to create the compelete mipmap chain.
    enableRenderSurfaces If true, the texture object will expose RenderSurface objects through GetRenderSurface(...).
    Returns:
    o3d.Texture2D.The Texture2D object.
    o3d.TextureCUBE Pack.createTextureCUBE ( number edgeLength
    o3d.Texture.Format format
    number levels
    boolean enableRenderSurfaces )

    Creates a new TextureCUBE object of the specified size and format and reserves the necessary resources for it. Note: If enable_render_surfaces is true, then the dimensions must be a power of two.

    Parameters:
    edgeLength The edge of the texture area in texels (max = 2048)
    format The memory format of each texel
    levels The number of mipmap levels. Use zero to create the compelete mipmap chain.
    enableRenderSurfaces If true, the texture object will expose RenderSurface objects through GetRenderSurface(...).
    Returns:
    o3d.TextureCUBE.The TextureCUBE object.
    o3d.Texture Pack.createTextureFromRawData ( !o3d.RawData rawData
    boolean generateMips )
    [**DEPRECATED**]

    Creates a Texture given a RawData object

    Parameters:
    rawData The RawData to create the texture from.
    generateMips True if you want O3D to generate mip maps for the texture.
    Returns:
    o3d.Texture.the Texture
    See Also:
    Pack.destroy ( )

    Removes all internal references to the Pack from the client. The pack, and all objects contained in it are permitted to be destroyed after the pack's destruction. Objects will only be destroyed after all references to them have been removed. NOTE: Calling pack.destroy does NOT free your resources. It justs releases the pack's reference to those resources. An example should hopefully make it clearer. pack.destroy() is effectively almost the same as this.

    var objectsInPack = pack.getObjectsByClassName('o3d.ObjectBase');
    for (var ii = 0; ii < objectsInPack.length; ++ii) {
      pack.removeObject(objectsInPack[ii]);
    }
    
    The only difference is that after all the objects are removed the pack itself will be released from the client. See documentation on pack.removeObject for why this is important. It's important to note that many objects are only referenced by the pack. Textures, Effects, Materials, for example. That means the moment you call pack.destroy() those objects will be freed. If the client then tries to render and some objects are missing you'll immediately get an error.
    !Array.<!o3d.ObjectBase> Pack.getObjects ( string name
    string classTypeName )

    Search the pack for all objects of a certain class with a certain name. Note that modifications to this array [e.g. push()] will not affect the underlying Pack, while modifications to the array's members will affect them.

    Parameters:
    name Name to look for
    classTypeName the Class of the object. It is okay to pass base types for example "o3d.RenderNode" will return ClearBuffers, DrawPasses, etc...
    Returns:
    !Array.<!o3d.ObjectBase>.Array of Objects.
    !Array.<!o3d.ObjectBase> Pack.getObjectsByClassName ( string classTypeName )

    Search the pack for all objects of a certain class Note that modifications to this array [e.g. push()] will not affect the underlying Pack, while modifications to the array's members will affect them.

    Parameters:
    classTypeName the Class of the object. It is okay to pass base types for example "o3d.RenderNode" will return ClearBuffers, DrawPasses, etc...
    Returns:
    !Array.<!o3d.ObjectBase>.Array of Objects.
    boolean Pack.isAClassName ( string className ) [inherited from o3d.ObjectBase]

    Takes the name of a class as an argument, and returns true if this object is either an instance of that class or derives from that class.

    var t = pack.createObject('o3d.Transform');
    t.isAClassName('o3d.Transform');    // true
    t.isAClassName('o3d.ParamObject');  // true
    t.isAClassName('o3d.Shape');        // false
    
    Parameters:
    className Name of class to check for.
    Returns:
    boolean.true if this object is a or is derived from the given class name.
    boolean Pack.removeObject ( !o3d.ObjectBase object )

    Removes a pack's reference to an object. Any object created from pack.create___ function can be removed. This releases the pack's reference to that object so if nothing else is referencing that object it will be deleted. NOTE: Calling pack.removeObject does NOT automatically free your resource. It just releases the pack's reference to that resource. An example should hopefully make it clearer. Suppose you make a transform like this:

    var myTransform = pack.createObject('Transform');
    myTransform.parent = g_client.root;
    pack.removeObject(myTransform);
    
    In the code above, myTransform is referenced twice. Once by the pack, and again by g_client.root So in this case, calling pack.removeObject() only releases the pack's reference leaving the reference by g_client.root.
    myTransform.parent = null;
    
    Now the last reference has been removed and myTransform will be freed.
    Parameters:
    object Object to remove.
    Returns:
    boolean.True if the object was successfully removed. False if the object is not part of this pack.
    See Also:

    Member Property Documentation

    string Pack.className [inherited from o3d.ObjectBase]

    The concrete class name for an object derived from ObjectBase. If you want to know if an object is of a certain type you should use objectBase.isAClassName

    var t = pack.createObject('o3d.Transform');
    t.className == 'o3d.Transform';  // true
    
    This property is read-only.
    number Pack.clientId [inherited from o3d.ObjectBase]

    Unique id of the object. This id will be unique, even across multiple O3D clients in the same page. This property is read-only.

    string Pack.name [inherited from o3d.NamedObject]

    The object's name. Setting this has no meaning to O3D, but is useful for debugging and for the functions Client.getObjects, Pack.getObject, RenderNode.getRenderNodesByNameInTree and RenderNode.getTransformsByNameInTree which search for objects by name.

    !Array.<!o3d.ObjectBase> Pack.objects

    All the objects managed by this pack. Each access to this field gets the entire list so it is best to get it just once. For example:

    var objects = pack.objects;
    for (var i = 0; i < objects.length; i++) {
      var object = objects[i];
    }
    
    Note that modifications to this array [e.g. push()] will not affect the underlying Pack, while modifications to the array's members will affect them. This property is read-only.