to top
Android APIs
public class

Allocation

extends BaseObj
java.lang.Object
   ↳ android.renderscript.BaseObj
     ↳ android.renderscript.Allocation
Known Direct Subclasses

Class Overview

Memory allocation class for renderscript. An allocation combines a Type with the memory to provide storage for user data and objects. This implies that all memory in Renderscript is typed.

Allocations are the primary way data moves into and out of scripts. Memory is user synchronized and it's possible for allocations to exist in multiple memory spaces concurrently. Currently those spaces are:

  • Script: accessable by RS scripts.
  • Graphics Texture: accessable as a graphics texture.
  • Graphics Vertex: accessable as graphical vertex data.
  • Graphics Constants: Accessable as constants in user shaders

For example, when creating a allocation for a texture, the user can specify its memory spaces as both script and textures. This means that it can both be used as script binding and as a GPU texture for rendering. To maintain synchronization if a script modifies an allocation used by other targets it must call a synchronizing function to push the updates to the memory, otherwise the results are undefined.

By default, Android system side updates are always applied to the script accessable memory. If this is not present, they are then applied to the various HW memory types. A syncAll() call is necessary after the script data is updated to keep the other memory spaces in sync.

Allocation data is uploaded in one of two primary ways. For simple arrays there are copyFrom() functions that take an array from the control code and copy it to the slave memory store. Both type checked and unchecked copies are provided. The unchecked variants exist to allow apps to copy over arrays of structures from a control language that does not support structures.

Developer Guides

For more information about creating an application that uses Renderscript, read the Renderscript developer guide.

Summary

Nested Classes
enum Allocation.MipmapControl Controls mipmap behavior when using the bitmap creation and update functions. 
Constants
int USAGE_GRAPHICS_CONSTANTS GRAPHICS_CONSTANTS The allocation will be used as the source of shader constants by one or more programs.
int USAGE_GRAPHICS_RENDER_TARGET USAGE_GRAPHICS_RENDER_TARGET The allocation will be used as a target for offscreen rendering
int USAGE_GRAPHICS_TEXTURE GRAPHICS_TEXTURE The allocation will be used as a texture source by one or more graphics programs.
int USAGE_GRAPHICS_VERTEX GRAPHICS_VERTEX The allocation will be used as a graphics mesh.
int USAGE_IO_INPUT USAGE_IO_INPUT The allocation will be used as SurfaceTexture consumer.
int USAGE_IO_OUTPUT USAGE_IO_OUTPUT The allocation will be used as a SurfaceTexture producer.
int USAGE_SCRIPT The usage of the allocation.
Public Methods
void copy1DRangeFrom(int off, int count, float[] d)
Copy part of an allocation from an array.
void copy1DRangeFrom(int off, int count, Allocation data, int dataOff)
Copy part of an allocation from another allocation.
void copy1DRangeFrom(int off, int count, short[] d)
Copy part of an allocation from an array.
void copy1DRangeFrom(int off, int count, int[] d)
Copy part of an allocation from an array.
void copy1DRangeFrom(int off, int count, byte[] d)
Copy part of an allocation from an array.
void copy1DRangeFromUnchecked(int off, int count, byte[] d)
Copy part of an allocation from an array.
void copy1DRangeFromUnchecked(int off, int count, short[] d)
Copy part of an allocation from an array.
void copy1DRangeFromUnchecked(int off, int count, float[] d)
Copy part of an allocation from an array.
void copy1DRangeFromUnchecked(int off, int count, int[] d)
Copy part of an allocation from an array.
void copy2DRangeFrom(int xoff, int yoff, int w, int h, float[] data)
void copy2DRangeFrom(int xoff, int yoff, int w, int h, byte[] data)
Copy a rectangular region from the array into the allocation.
void copy2DRangeFrom(int xoff, int yoff, int w, int h, int[] data)
void copy2DRangeFrom(int xoff, int yoff, int w, int h, short[] data)
void copy2DRangeFrom(int xoff, int yoff, Bitmap data)
Copy a bitmap into an allocation.
void copy2DRangeFrom(int xoff, int yoff, int w, int h, Allocation data, int dataXoff, int dataYoff)
Copy a rectangular region into the allocation from another allocation.
void copyFrom(BaseObj[] d)
Copy an array of RS objects to the allocation.
void copyFrom(byte[] d)
Copy an allocation from an array.
void copyFrom(int[] d)
Copy an allocation from an array.
void copyFrom(float[] d)
Copy an allocation from an array.
void copyFrom(Bitmap b)
Copy an allocation from a bitmap.
void copyFrom(short[] d)
Copy an allocation from an array.
void copyFromUnchecked(int[] d)
Copy an allocation from an array.
void copyFromUnchecked(short[] d)
Copy an allocation from an array.
void copyFromUnchecked(byte[] d)
Copy an allocation from an array.
void copyFromUnchecked(float[] d)
Copy an allocation from an array.
void copyTo(byte[] d)
Copy from the Allocation into a byte array.
void copyTo(int[] d)
Copy from the Allocation into a int array.
void copyTo(float[] d)
Copy from the Allocation into a float array.
void copyTo(short[] d)
Copy from the Allocation into a short array.
void copyTo(Bitmap b)
Copy from the Allocation into a Bitmap.
static Allocation createCubemapFromBitmap(RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)
Creates a cubemap allocation from a bitmap containing the horizontal list of cube faces.
static Allocation createCubemapFromBitmap(RenderScript rs, Bitmap b)
Creates a non-mipmapped cubemap allocation for use as a graphics texture from a bitmap containing the horizontal list of cube faces.
static Allocation createCubemapFromCubeFaces(RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg)
Creates a non-mipmapped cubemap allocation for use as a graphics texture from 6 bitmaps containing the cube faces.
static Allocation createCubemapFromCubeFaces(RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg, Allocation.MipmapControl mips, int usage)
Creates a cubemap allocation from 6 bitmaps containing the cube faces.
static Allocation createFromBitmap(RenderScript rs, Bitmap b)
Creates a non-mipmapped renderscript allocation to use as a graphics texture
static Allocation createFromBitmap(RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)
Creates a renderscript allocation from a bitmap
static Allocation createFromBitmapResource(RenderScript rs, Resources res, int id)
Creates a non-mipmapped renderscript allocation to use as a graphics texture from the bitmap referenced by resource id
static Allocation createFromBitmapResource(RenderScript rs, Resources res, int id, Allocation.MipmapControl mips, int usage)
Creates a renderscript allocation from the bitmap referenced by resource id
static Allocation createFromString(RenderScript rs, String str, int usage)
Creates a renderscript allocation containing string data encoded in UTF-8 format
static Allocation createSized(RenderScript rs, Element e, int count)
Creates a renderscript allocation with a specified number of given elements
static Allocation createSized(RenderScript rs, Element e, int count, int usage)
Creates a renderscript allocation with a specified number of given elements
static Allocation createTyped(RenderScript rs, Type type)
Creates a renderscript allocation for use by the script with the size specified by the type and no mipmaps generated by default
static Allocation createTyped(RenderScript rs, Type type, int usage)
Creates a renderscript allocation with the size specified by the type and no mipmaps generated by default
static Allocation createTyped(RenderScript rs, Type type, Allocation.MipmapControl mips, int usage)
void generateMipmaps()
Generate a mipmap chain.
int getBytesSize()
Get the size of the Allocation in bytes.
Element getElement()
Get the element of the type of the Allocation.
Surface getSurface()
For allocations used with io operations, returns the handle onto a raw buffer that is being managed by the screen compositor.
Type getType()
Get the type of the Allocation.
int getUsage()
Get the usage flags of the Allocation.
void ioReceive()
Receive the latest input into the Allocation.
void ioSend()
Send a buffer to the output stream.
synchronized void resize(int dimX)
Resize a 1D allocation.
void setFromFieldPacker(int xoff, FieldPacker fp)
This is only intended to be used by auto-generate code reflected from the renderscript script files.
void setFromFieldPacker(int xoff, int component_number, FieldPacker fp)
This is only intended to be used by auto-generate code reflected from the renderscript script files.
void setSurface(Surface sur)
Associate a surface for io output with this allocation
void syncAll(int srcLocation)
Propagate changes from one usage of the allocation to the remaining usages of the allocation.
[Expand]
Inherited Methods
From class android.renderscript.BaseObj
From class java.lang.Object

Constants

public static final int USAGE_GRAPHICS_CONSTANTS

Since: API Level 11

GRAPHICS_CONSTANTS The allocation will be used as the source of shader constants by one or more programs.

Constant Value: 8 (0x00000008)

public static final int USAGE_GRAPHICS_RENDER_TARGET

Since: API Level 14

USAGE_GRAPHICS_RENDER_TARGET The allocation will be used as a target for offscreen rendering

Constant Value: 16 (0x00000010)

public static final int USAGE_GRAPHICS_TEXTURE

Since: API Level 11

GRAPHICS_TEXTURE The allocation will be used as a texture source by one or more graphics programs.

Constant Value: 2 (0x00000002)

public static final int USAGE_GRAPHICS_VERTEX

Since: API Level 11

GRAPHICS_VERTEX The allocation will be used as a graphics mesh.

Constant Value: 4 (0x00000004)

public static final int USAGE_IO_INPUT

Since: API Level 16

USAGE_IO_INPUT The allocation will be used as SurfaceTexture consumer. This usage will cause the allocation to be created read only.

Constant Value: 32 (0x00000020)

public static final int USAGE_IO_OUTPUT

Since: API Level 16

USAGE_IO_OUTPUT The allocation will be used as a SurfaceTexture producer. The dimensions and format of the SurfaceTexture will be forced to those of the allocation.

Constant Value: 64 (0x00000040)

public static final int USAGE_SCRIPT

Since: API Level 11

The usage of the allocation. These signal to renderscript where to place the allocation in memory. SCRIPT The allocation will be bound to and accessed by scripts.

Constant Value: 1 (0x00000001)

Public Methods

public void copy1DRangeFrom (int off, int count, float[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 32 bit float type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array.

public void copy1DRangeFrom (int off, int count, Allocation data, int dataOff)

Since: API Level 14

Copy part of an allocation from another allocation.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
data the source data allocation.
dataOff off The offset of the first element in data to be copied.

public void copy1DRangeFrom (int off, int count, short[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 16 bit integer type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFrom (int off, int count, int[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 32 bit integer type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFrom (int off, int count, byte[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 8 bit integer type.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, byte[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, short[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, float[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy1DRangeFromUnchecked (int off, int count, int[] d)

Since: API Level 11

Copy part of an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
off The offset of the first element to be copied.
count The number of elements to be copied.
d the source data array

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, float[] data)

Since: API Level 11

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, byte[] data)

Since: API Level 11

Copy a rectangular region from the array into the allocation. The incoming array is assumed to be tightly packed.

Parameters
xoff X offset of the region to update
yoff Y offset of the region to update
w Width of the incoming region to update
h Height of the incoming region to update
data to be placed into the allocation

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, int[] data)

Since: API Level 11

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, short[] data)

Since: API Level 11

public void copy2DRangeFrom (int xoff, int yoff, Bitmap data)

Since: API Level 11

Copy a bitmap into an allocation. The height and width of the update will use the height and width of the incoming bitmap.

Parameters
xoff X offset of the region to update
yoff Y offset of the region to update
data the bitmap to be copied

public void copy2DRangeFrom (int xoff, int yoff, int w, int h, Allocation data, int dataXoff, int dataYoff)

Since: API Level 14

Copy a rectangular region into the allocation from another allocation.

Parameters
xoff X offset of the region to update.
yoff Y offset of the region to update.
w Width of the incoming region to update.
h Height of the incoming region to update.
data source allocation.
dataXoff X offset in data of the region to update.
dataYoff Y offset in data of the region to update.

public void copyFrom (BaseObj[] d)

Since: API Level 11

Copy an array of RS objects to the allocation.

Parameters
d Source array.

public void copyFrom (byte[] d)

Since: API Level 11

Copy an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 8 bit integer type.

Parameters
d the source data array

public void copyFrom (int[] d)

Since: API Level 11

Copy an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 32 bit integer type.

Parameters
d the source data array

public void copyFrom (float[] d)

Since: API Level 11

Copy an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 32 bit float type.

Parameters
d the source data array

public void copyFrom (Bitmap b)

Since: API Level 11

Copy an allocation from a bitmap. The height, width, and format of the bitmap must match the existing allocation.

Parameters
b the source bitmap

public void copyFrom (short[] d)

Since: API Level 11

Copy an allocation from an array. This variant is type checked and will generate exceptions if the Allocation type is not a 16 bit integer type.

Parameters
d the source data array

public void copyFromUnchecked (int[] d)

Since: API Level 11

Copy an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
d the source data array

public void copyFromUnchecked (short[] d)

Since: API Level 11

Copy an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
d the source data array

public void copyFromUnchecked (byte[] d)

Since: API Level 11

Copy an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
d the source data array

public void copyFromUnchecked (float[] d)

Since: API Level 11

Copy an allocation from an array. This variant is not type checked which allows an application to fill in structured data from an array.

Parameters
d the source data array

public void copyTo (byte[] d)

Since: API Level 11

Copy from the Allocation into a byte array. The array must be at least as large as the Allocation. The allocation must be of an 8 bit elemental type.

Parameters
d The array to be set from the Allocation.

public void copyTo (int[] d)

Since: API Level 11

Copy from the Allocation into a int array. The array must be at least as large as the Allocation. The allocation must be of an 32 bit elemental type.

Parameters
d The array to be set from the Allocation.

public void copyTo (float[] d)

Since: API Level 11

Copy from the Allocation into a float array. The array must be at least as large as the Allocation. The allocation must be of an 32 bit float elemental type.

Parameters
d The array to be set from the Allocation.

public void copyTo (short[] d)

Since: API Level 11

Copy from the Allocation into a short array. The array must be at least as large as the Allocation. The allocation must be of an 16 bit elemental type.

Parameters
d The array to be set from the Allocation.

public void copyTo (Bitmap b)

Since: API Level 11

Copy from the Allocation into a Bitmap. The bitmap must match the dimensions of the Allocation.

Parameters
b The bitmap to be set from the Allocation.

public static Allocation createCubemapFromBitmap (RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)

Since: API Level 11

Creates a cubemap allocation from a bitmap containing the horizontal list of cube faces. Each individual face must be the same size and power of 2

Parameters
rs Context to which the allocation will belong.
b bitmap with cubemap faces layed out in the following format: right, left, top, bottom, front, back
mips specifies desired mipmap behaviour for the cubemap
usage bit field specifying how the cubemap is utilized
Returns
  • allocation containing cubemap data

public static Allocation createCubemapFromBitmap (RenderScript rs, Bitmap b)

Since: API Level 11

Creates a non-mipmapped cubemap allocation for use as a graphics texture from a bitmap containing the horizontal list of cube faces. Each individual face must be the same size and power of 2

Parameters
rs Context to which the allocation will belong.
b bitmap with cubemap faces layed out in the following format: right, left, top, bottom, front, back
Returns
  • allocation containing cubemap data

public static Allocation createCubemapFromCubeFaces (RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg)

Since: API Level 11

Creates a non-mipmapped cubemap allocation for use as a graphics texture from 6 bitmaps containing the cube faces. All the faces must be the same size and power of 2

Parameters
rs Context to which the allocation will belong.
xpos cubemap face in the positive x direction
xneg cubemap face in the negative x direction
ypos cubemap face in the positive y direction
yneg cubemap face in the negative y direction
zpos cubemap face in the positive z direction
zneg cubemap face in the negative z direction
Returns
  • allocation containing cubemap data

public static Allocation createCubemapFromCubeFaces (RenderScript rs, Bitmap xpos, Bitmap xneg, Bitmap ypos, Bitmap yneg, Bitmap zpos, Bitmap zneg, Allocation.MipmapControl mips, int usage)

Since: API Level 11

Creates a cubemap allocation from 6 bitmaps containing the cube faces. All the faces must be the same size and power of 2

Parameters
rs Context to which the allocation will belong.
xpos cubemap face in the positive x direction
xneg cubemap face in the negative x direction
ypos cubemap face in the positive y direction
yneg cubemap face in the negative y direction
zpos cubemap face in the positive z direction
zneg cubemap face in the negative z direction
mips specifies desired mipmap behaviour for the cubemap
usage bit field specifying how the cubemap is utilized
Returns
  • allocation containing cubemap data

public static Allocation createFromBitmap (RenderScript rs, Bitmap b)

Since: API Level 11

Creates a non-mipmapped renderscript allocation to use as a graphics texture

Parameters
rs Context to which the allocation will belong.
b bitmap source for the allocation data
Returns
  • renderscript allocation containing bitmap data

public static Allocation createFromBitmap (RenderScript rs, Bitmap b, Allocation.MipmapControl mips, int usage)

Since: API Level 11

Creates a renderscript allocation from a bitmap

Parameters
rs Context to which the allocation will belong.
b bitmap source for the allocation data
mips specifies desired mipmap behaviour for the allocation
usage bit field specifying how the allocation is utilized
Returns
  • renderscript allocation containing bitmap data

public static Allocation createFromBitmapResource (RenderScript rs, Resources res, int id)

Since: API Level 11

Creates a non-mipmapped renderscript allocation to use as a graphics texture from the bitmap referenced by resource id

Parameters
rs Context to which the allocation will belong.
res application resources
id resource id to load the data from
Returns
  • renderscript allocation containing resource data

public static Allocation createFromBitmapResource (RenderScript rs, Resources res, int id, Allocation.MipmapControl mips, int usage)

Since: API Level 11

Creates a renderscript allocation from the bitmap referenced by resource id

Parameters
rs Context to which the allocation will belong.
res application resources
id resource id to load the data from
mips specifies desired mipmap behaviour for the allocation
usage bit field specifying how the allocation is utilized
Returns
  • renderscript allocation containing resource data

public static Allocation createFromString (RenderScript rs, String str, int usage)

Since: API Level 11

Creates a renderscript allocation containing string data encoded in UTF-8 format

Parameters
rs Context to which the allocation will belong.
str string to create the allocation from
usage bit field specifying how the allocaiton is utilized

public static Allocation createSized (RenderScript rs, Element e, int count)

Since: API Level 11

Creates a renderscript allocation with a specified number of given elements

Parameters
rs Context to which the allocation will belong.
e describes what each element of an allocation is
count specifies the number of element in the allocation
Returns
  • allocation

public static Allocation createSized (RenderScript rs, Element e, int count, int usage)

Since: API Level 11

Creates a renderscript allocation with a specified number of given elements

Parameters
rs Context to which the allocation will belong.
e describes what each element of an allocation is
count specifies the number of element in the allocation
usage bit field specifying how the allocation is utilized
Returns
  • allocation

public static Allocation createTyped (RenderScript rs, Type type)

Since: API Level 11

Creates a renderscript allocation for use by the script with the size specified by the type and no mipmaps generated by default

Parameters
rs Context to which the allocation will belong.
type renderscript type describing data layout
Returns
  • allocation

public static Allocation createTyped (RenderScript rs, Type type, int usage)

Since: API Level 11

Creates a renderscript allocation with the size specified by the type and no mipmaps generated by default

Parameters
rs Context to which the allocation will belong.
type renderscript type describing data layout
usage bit field specifying how the allocation is utilized
Returns
  • allocation

public static Allocation createTyped (RenderScript rs, Type type, Allocation.MipmapControl mips, int usage)

Since: API Level 11

Parameters
type renderscript type describing data layout
mips specifies desired mipmap behaviour for the allocation
usage bit field specifying how the allocation is utilized

public void generateMipmaps ()

Since: API Level 11

Generate a mipmap chain. Requires the type of the allocation include mipmaps. This function will generate a complete set of mipmaps from the top level lod and place them into the script memoryspace. If the allocation is also using other memory spaces a followup sync will be required.

public int getBytesSize ()

Since: API Level 16

Get the size of the Allocation in bytes.

Returns
  • size of the Allocation in bytes.

public Element getElement ()

Since: API Level 16

Get the element of the type of the Allocation.

Returns
  • Element that describes the structure of data in the allocation

public Surface getSurface ()

Since: API Level 16

For allocations used with io operations, returns the handle onto a raw buffer that is being managed by the screen compositor.

Returns
  • Surface object associated with allocation

public Type getType ()

Since: API Level 11

Get the type of the Allocation.

Returns
  • Type

public int getUsage ()

Since: API Level 16

Get the usage flags of the Allocation.

Returns
  • usage flags associated with the allocation. e.g. script, texture, etc.

public void ioReceive ()

Since: API Level 16

Receive the latest input into the Allocation.

public void ioSend ()

Since: API Level 16

Send a buffer to the output stream. The contents of the Allocation will be undefined after this operation.

public synchronized void resize (int dimX)

Since: API Level 11

Resize a 1D allocation. The contents of the allocation are preserved. If new elements are allocated objects are created with null contents and the new region is otherwise undefined. If the new region is smaller the references of any objects outside the new region will be released. A new type will be created with the new dimension.

Parameters
dimX The new size of the allocation.

public void setFromFieldPacker (int xoff, FieldPacker fp)

Since: API Level 11

This is only intended to be used by auto-generate code reflected from the renderscript script files.

public void setFromFieldPacker (int xoff, int component_number, FieldPacker fp)

Since: API Level 11

This is only intended to be used by auto-generate code reflected from the renderscript script files.

public void setSurface (Surface sur)

Since: API Level 16

Associate a surface for io output with this allocation

Parameters
sur Surface to associate with allocation

public void syncAll (int srcLocation)

Since: API Level 11

Propagate changes from one usage of the allocation to the remaining usages of the allocation.