SetRasterImageAllocateCallback Method

Sets a global callback to be called whenever the toolkit is creating a new RasterImage object.

Syntax

C#
Visual Basic
WinRT C#
Objective-C
Java
WinRT JavaScript
C++

public static RasterImageAllocateCallback SetRasterImageAllocateCallback( 
   RasterImageAllocateCallback callback
)

'Declaration
 
Public Shared Function SetRasterImageAllocateCallback( _
   ByVal callback As RasterImageAllocateCallback _
) As RasterImageAllocateCallback

'Usage
 
Dim callback As RasterImageAllocateCallback
Dim value As RasterImageAllocateCallback
 
value = RasterDefaults.SetRasterImageAllocateCallback(callback)

public static RasterImageAllocateCallback SetRasterImageAllocateCallback( 
   RasterImageAllocateCallback callback
)

 function Leadtools.RasterDefaults.SetRasterImageAllocateCallback( 
   callback 
)

public:
static RasterImageAllocateCallback^ SetRasterImageAllocateCallback( 
   RasterImageAllocateCallback^ callback
)

Parameters

callback: Method to be called whenever the toolkit is creating a new RasterImage object. You can pass null (Nothing in Visual Basic) to stop the toolkit from calling any callback.

Return Value

The previous global callback set, or null (Nothing in Visual Basic) if no callback was set before (default).

Remarks

This method allows you to inspect (and change the memory model being used) whenever the toolkit is creating a new RasterImage object. Generally, you can use the RasterMemoryFlags argument to the RasterImage constructor when creating new objects, however, in some instances, the toolkit will create images internally and you have no control on the memory model being passed. The callback set is global to all LEADTOOLS used in current process.

This can be useful for debugging purposes or to control the memory model of an image being creating internally in LEADTOOLS, for example, as a result of an image processing operation as described in the example.

The return value is the old callback set previously by the user, if no callback was set previously, this method will return null (Nothing in Visual Basic), this allow you to cascade callbacks together.

By default, the toolkit does not set a callback, and calling this method the first time will always return null (Nothing in Visual Basic).

When you are done when the callback, you can call this method with a null (Nothing in Visual Basic) reference to stop the toolkit from calling any methods when creating RasterImage objects.

Example

C#
Visual Basic
WinRT C#
WinRT JavaScript
Silverlight C#
Silverlight VB

Copy Code

Imports Leadtools
Imports Leadtools.Codecs
Imports Leadtools.ImageProcessing

Private Sub SetRasterImageAllocateCallbackExample()
   Try
      ' Set the LEADTOOLS temporary directory to a value we can watch easily
      RasterDefaults.TemporaryDirectory = "C:\Temp\LEADTOOLS"
      ' Install a callback to notify us when LEADTOOLS images are created
      ' IMPORTANT: SetRasterImageAllocateCallback is global and not thread safe. It will fire
      ' for each image being created after this point, so if the action you are performing in the
      ' callback requires synchronzation, add the required code. For what this sample is trying
      ' to accomplish, our solution is perfectly safe and no synchronization is needed.
      RasterDefaults.SetRasterImageAllocateCallback(AddressOf MyRasterImageAllocateCallback)

      ' We want conventional memory and nothing else
      Dim flags As RasterMemoryFlags = RasterMemoryFlags.Conventional Or RasterMemoryFlags.NoDisk Or RasterMemoryFlags.NoTiled
      ' Create a huge RasterImage
      Using img As RasterImage = New RasterImage(flags, 20000, 20000, 24, RasterByteOrder.Bgr, RasterViewPerspective.TopLeft, Nothing, Nothing, 0)
         ' Rotate it 90 degrees, this will have a memory size greater than the default
         ' size of conventional memory and cause LEADTOOLS to switch to a disk or tiled memory
         ' model. In the callback below, we instruct LEADTOOLS to only use conventional memory so the command
         ' will throw an out of memory exception as expected.
         Dim cmd As New RotateCommand
         cmd.Angle = 90 * 100
         ' Exception will be thrown inside here: No Memory since our callback
         ' will be called and we instruct LEADTOOLS to not use disk
         cmd.Run(img)
      End Using
   Catch ex As Exception
      ' Show the error
      Console.WriteLine(ex.Message)
   End Try
End Sub

Private Shared Function MyRasterImageAllocateCallback(ByVal data As RasterImageAllocateData) As RasterExceptionCode
   Console.WriteLine("Trying to allocate:")
   Console.WriteLine("   Memory: {0}", data.MemoryFlags)
   Console.WriteLine("   Size: {0} by {1}", data.Width, data.Height)
   Console.WriteLine("   BPP: {0}, Order: {1}", data.BitsPerPixel, data.Order)
   Console.WriteLine("   Size: {0}", data.Size)

   ' Note, all values beside MemoryFlags are read only and cannot be changed

   ' We want conventional memory and nothing else, so change this
   data.MemoryFlags = RasterMemoryFlags.Conventional Or RasterMemoryFlags.NoTiled Or RasterMemoryFlags.NoDisk

   ' If you remove the code above, the toolkit will most probably switch to disk or tiled memory model
   ' and creating this huge image will be successful, however, we only want conventional
   ' memory in this example, and out of memory exception is the expected behavior of this
   ' example

   ' Let LEADTOOLS continue with creating the image process
   ' You can return any other value to abort
   Return RasterExceptionCode.Success
End Function

using Leadtools;
using Leadtools.Codecs;

private void SetRasterImageAllocateCallbackExample()
{
   try
   {
      // Set the LEADTOOLS temporary directory to a value we can watch easily
      RasterDefaults.TemporaryDirectory = Path.Combine(ImagesPath.Path,@"Temp\LEADTOOLS");
      // Install a callback to notify us when LEADTOOLS images are created
      // IMPORTANT: SetRasterImageAllocateCallback is global and not thread safe. It will fire
      // for each image being created after this point, so if the action you are performing in the
      // callback requires synchronzation, add the required code. For what this sample is trying
      // to accomplish, our solution is perfectly safe and no synchronization is needed.
      RasterDefaults.SetRasterImageAllocateCallback(new RasterImageAllocateCallback(MyRasterImageAllocateCallback));

      // We want conventional memory and nothing else
      RasterMemoryFlags flags = RasterMemoryFlags.Conventional | RasterMemoryFlags.NoDisk | RasterMemoryFlags.NoTiled;
      // Create a huge RasterImage
      using(RasterImage img = new RasterImage(flags, 20000, 20000, 24, RasterByteOrder.Bgr, RasterViewPerspective.TopLeft, null, null, 0))
      {
         // Rotate it 90 degrees, this will have a memory size greater than the default
         // size of conventional memory and cause LEADTOOLS to switch to a disk or tiled memory
         // model. In the callback below, we instruct LEADTOOLS to only use conventional memory so the command
         // will throw an out of memory exception as expected.
         Leadtools.ImageProcessing.RotateCommand cmd = new Leadtools.ImageProcessing.RotateCommand();
         cmd.Angle = 90 * 100;
         // Exception will be thrown inside here: No Memory since our callback
         // will be called and we instruct LEADTOOLS to not use disk
         cmd.Run(img);
      }
   }
   catch(Exception ex)
   {
      // Show the error
      Console.WriteLine(ex.Message);
   }
}

private static RasterExceptionCode MyRasterImageAllocateCallback(RasterImageAllocateData data)
{
   Console.WriteLine("Trying to allocate:");
   Console.WriteLine("   Memory: {0}", data.MemoryFlags);
   Console.WriteLine("   Size: {0} by {1}", data.Width, data.Height);
   Console.WriteLine("   BPP: {0}, Order: {1}", data.BitsPerPixel, data.Order);
   Console.WriteLine("   Size: {0}", data.Size);

   // Note, all values beside MemoryFlags are read only and cannot be changed

   // We want conventional memory and nothing else, so change this
   data.MemoryFlags = RasterMemoryFlags.Conventional | RasterMemoryFlags.NoTiled | RasterMemoryFlags.NoDisk;

   // If you remove the code above, the toolkit will most probably switch to disk or tiled memory model
   // and creating this huge image will be successful, however, we only want conventional
   // memory in this example, and out of memory exception is the expected behavior of this
   // example

   // Let LEADTOOLS continue with creating the image process
   // You can return any other value to abort
   return RasterExceptionCode.Success;
}

RasterDefaultsExample.prototype.SetRasterImageAllocateCallbackExample = function ()
{
   with ( Leadtools ) 
   {
      try
      {
         // Install a callback to notify us when LEADTOOLS images are created
         // IMPORTANT: SetRasterImageAllocateCallback is global and not thread safe. It will fire
         // for each image being created after this point, so if the action you are performing in the
         // callback requires synchronzation, add the required code. For what this sample is trying
         // to accomplish, our solution is perfectly safe and no synchronization is needed.
         RasterDefaults.setRasterImageAllocateCallback(MyRasterImageAllocateCallback);

         // We want conventional memory and nothing else
         var flags = RasterMemoryFlags.conventional | RasterMemoryFlags.noDisk | RasterMemoryFlags.noTiled;
         // Create a huge RasterImage
         var img = new RasterImage(flags, 2000, 2000, 24, RasterByteOrder.bgr, RasterViewPerspective.topLeft, null)
   
         // Rotate it 90 degrees, this will have a memory size greater than the default
         // size of conventional memory and cause LEADTOOLS to switch to a disk or tiled memory
         // model. In the callback below, we instruct LEADTOOLS to only use conventional memory so the command
         // will throw an out of memory exception as expected.
         var cmd = new Leadtools.ImageProcessing.RotateCommand();
         cmd.angle = 90 * 100;
         // Exception will be thrown inside here: No Memory since our callback
         // will be called and we instruct LEADTOOLS to not use disk
         cmd.run(img);
      }
      catch(error)
      {
         // Show the error
         console.error(error.message);
         throw error;
      }
   }
}

function MyRasterImageAllocateCallback( data)
{
   with ( Leadtools ) 
   {
      console.info("Trying to allocate:");
      console.info("   Memory: ", data.memoryFlags);
      console.info("   Size: " + data.width + " by ", data.height);
      console.info("   BPP: " + data.bitsPerPixel + ", Order: ", data.order);
      console.info("   Size: ", data.size);

      // Note, all values beside MemoryFlags are read only and cannot be changed

      // We want conventional memory and nothing else, so change this
      data.memoryFlags = RasterMemoryFlags.conventional | RasterMemoryFlags.noTiled | RasterMemoryFlags.noDisk;

      // If you remove the code above, the toolkit will most probably switch to disk or tiled memory model
      // and creating this huge image will be successful, however, we only want conventional
      // memory in this example, and out of memory exception is the expected behavior of this
      // example

      // Let LEADTOOLS continue with creating the image process
      // You can return any other value to abort
      return RasterExceptionCode.success;
   }

using Leadtools;
using Leadtools.Codecs;

private void SetRasterImageAllocateCallbackExample()
{
   try
   {
      // Set the LEADTOOLS temporary directory to a value we can watch easily
      RasterDefaults.TemporaryDirectory = Tools.AppLocalFolder.Path;
      // Install a callback to notify us when LEADTOOLS images are created
      // IMPORTANT: SetRasterImageAllocateCallback is global and not thread safe. It will fire
      // for each image being created after this point, so if the action you are performing in the
      // callback requires synchronzation, add the required code. For what this sample is trying
      // to accomplish, our solution is perfectly safe and no synchronization is needed.
      RasterDefaults.SetRasterImageAllocateCallback(new RasterImageAllocateCallback(MyRasterImageAllocateCallback));

      // We want conventional memory and nothing else
      RasterMemoryFlags flags = RasterMemoryFlags.Conventional | RasterMemoryFlags.NoDisk | RasterMemoryFlags.NoTiled;
      // Create a huge RasterImage
      using(RasterImage img = new RasterImage(flags, 20000, 20000, 24, RasterByteOrder.Bgr, RasterViewPerspective.TopLeft, null))
      {
         // Rotate it 90 degrees, this will have a memory size greater than the default
         // size of conventional memory and cause LEADTOOLS to switch to a disk or tiled memory
         // model. In the callback below, we instruct LEADTOOLS to only use conventional memory so the command
         // will throw an out of memory exception as expected.
         Leadtools.ImageProcessing.RotateCommand cmd = new Leadtools.ImageProcessing.RotateCommand();
         cmd.Angle = 90 * 100;
         // Exception will be thrown inside here: No Memory since our callback
         // will be called and we instruct LEADTOOLS to not use disk
         cmd.Run(img);
      }
   }
   catch(Exception ex)
   {
      // Show the error
      Debug.WriteLine(ex.Message);
   }
}

private static RasterExceptionCode MyRasterImageAllocateCallback(RasterImageAllocateData data)
{
   Debug.WriteLine("Trying to allocate:");
   Debug.WriteLine("   Memory: {0}", data.MemoryFlags);
   Debug.WriteLine("   Size: {0} by {1}", data.Width, data.Height);
   Debug.WriteLine("   BPP: {0}, Order: {1}", data.BitsPerPixel, data.Order);
   Debug.WriteLine("   Size: {0}", data.Size);

   // Note, all values beside MemoryFlags are read only and cannot be changed

   // We want conventional memory and nothing else, so change this
   data.MemoryFlags = RasterMemoryFlags.Conventional | RasterMemoryFlags.NoTiled | RasterMemoryFlags.NoDisk;

   // If you remove the code above, the toolkit will most probably switch to disk or tiled memory model
   // and creating this huge image will be successful, however, we only want conventional
   // memory in this example, and out of memory exception is the expected behavior of this
   // example

   // Let LEADTOOLS continue with creating the image process
   // You can return any other value to abort
   return RasterExceptionCode.Success;
}

Requirements

Target Platforms

Reference

RasterDefaults Class
RasterDefaults Members