# IRdBitmapDisp Interface Reference

Inherits IDispatch, and IDispatch.

List of all members.

## Public Member Functions
HRESULT | Clear (void)
HRESULT | Create ([in] RtDWORD nWidth,[in] RtDWORD nHeight,[in] RtPixelFormat PixelFormat)
HRESULT | CreateEx ([in] RtDWORD nWidth,[in] RtDWORD nHeight,[in] BSTR bsFormat)
HRESULT | ConvertFormat ([in] RtPixelFormat pFormat)
HRESULT | GetHeader ([out] RtDWORD *pdwWidth,[out] RtDWORD *pdwHeight,[out] RtPixelFormat *pFormat)
HRESULT | GetSizeX ([out, retval] RtDWORD *pOut)
HRESULT | GetSizeY ([out, retval] RtDWORD *pOut)
HRESULT | GetFormatString ([out, retval] BSTR *pOut)
HRESULT | GetFormat ([out, retval] RtPixelFormat *pOut)
HRESULT | GetFormatNumberFromString ([in] BSTR bsFormat,[out, retval] RtPixelFormat *pOut)
HRESULT | GetFormatStringFromNumber ([in] RtPixelFormat Format,[out, retval] BSTR *pOut)
HRESULT | GetPixel ([in] RtDWORD dwPositionX,[in] RtDWORD dwPositionY,[in] IDispatch *pOutValue)
HRESULT | SetPixel ([in] RtDWORD dwPositionX,[in] RtDWORD dwPositionY,[in] IDispatch *pInValue)
HRESULT | GetPixelCOLORREF ([in] RtDWORD dwPositionX,[in] RtDWORD dwPositionY,[out, retval] COLORREF *pOutValue)
HRESULT | LockBitmap ()
HRESULT | UnlockBitmap ()
HRESULT | LoadFromFile ([in] BSTR FileName)
HRESULT | GetFileName ([out, retval] BSTR *pFileName)
HRESULT | SetIsFromFile ([in] RtBool bIsFromFile,[in] BSTR bstrFileName)
HRESULT | SaveToFile ([in] RtBitmapFileFormat Format,[in] BSTR FileName)
HRESULT | Resize ([in] RtDWORD dwWidth,[in] RtDWORD dwHeight)
HRESULT | GetSupportedFormatCount ([out, retval] DWORD *dwFormatCount)
HRESULT | GetSupportedFormatMasks ([in] DWORD dwFormat,[out, retval] BSTR *bsMasks)
HRESULT | GetSupportedFormatName ([in] DWORD dwFormat,[out, retval] BSTR *bsFormatName)
HRESULT | IsEqual ([in] IDispatch *pBitmap,[out, retval] BOOL *bEqualityResult)
HRESULT | GetImageSizeFromFile ([in] BSTR FileName,[out, retval] VARIANT *pvRetInfo)
HRESULT | GetDownsampledFlag ([out, retval] RtBool *pVal)
HRESULT | SetDownsampledFlag ([in] RtBool newVal)
HRESULT | SaveToFileEx ([in] RtBitmapFileFormat Format,[in] BSTR FileName)
HRESULT | Clear (void)
HRESULT | Create ([in] RtDWORD nWidth,[in] RtDWORD nHeight,[in] RtPixelFormat PixelFormat)
HRESULT | CreateEx ([in] RtDWORD nWidth,[in] RtDWORD nHeight,[in] BSTR bsFormat)
HRESULT | ConvertFormat ([in] RtPixelFormat pFormat)
HRESULT | GetHeader ([out] RtDWORD *pdwWidth,[out] RtDWORD *pdwHeight,[out] RtPixelFormat *pFormat)
HRESULT | GetSizeX ([out, retval] RtDWORD *pOut)
HRESULT | GetSizeY ([out, retval] RtDWORD *pOut)
HRESULT | GetFormatString ([out, retval] BSTR *pOut)
HRESULT | GetFormat ([out, retval] RtPixelFormat *pOut)
HRESULT | GetFormatNumberFromString ([in] BSTR bsFormat,[out, retval] RtPixelFormat *pOut)
HRESULT | GetFormatStringFromNumber ([in] RtPixelFormat Format,[out, retval] BSTR *pOut)
HRESULT | GetPixel ([in] RtDWORD dwPositionX,[in] RtDWORD dwPositionY,[in] IDispatch *pOutValue)
HRESULT | SetPixel ([in] RtDWORD dwPositionX,[in] RtDWORD dwPositionY,[in] IDispatch *pInValue)
HRESULT | GetPixelCOLORREF ([in] RtDWORD dwPositionX,[in] RtDWORD dwPositionY,[out, retval] COLORREF *pOutValue)
HRESULT | LockBitmap ()
HRESULT | UnlockBitmap ()
HRESULT | LoadFromFile ([in] BSTR FileName)
HRESULT | GetFileName ([out, retval] BSTR *pFileName)
HRESULT | SetIsFromFile ([in] RtBool bIsFromFile,[in] BSTR bstrFileName)
HRESULT | SaveToFile ([in] RtBitmapFileFormat Format,[in] BSTR FileName)
HRESULT | Resize ([in] RtDWORD dwWidth,[in] RtDWORD dwHeight)
HRESULT | GetSupportedFormatCount ([out, retval] DWORD *dwFormatCount)
HRESULT | GetSupportedFormatMasks ([in] DWORD dwFormat,[out, retval] BSTR *bsMasks)
HRESULT | GetSupportedFormatName ([in] DWORD dwFormat,[out, retval] BSTR *bsFormatName)
HRESULT | IsEqual ([in] IDispatch *pBitmap,[out, retval] BOOL *bEqualityResult)
HRESULT | GetImageSizeFromFile ([in] BSTR FileName,[out, retval] VARIANT *pvRetInfo)
HRESULT | GetDownsampledFlag ([out, retval] RtBool *pVal)
HRESULT | SetDownsampledFlag ([in] RtBool newVal)
HRESULT | SaveToFileEx ([in] RtBitmapFileFormat Format,[in] BSTR FileName)

## Detailed Description

Specifies dispatch (scriptable) version of the IRdBitmap interface.

Warning:
  this bitmap has to be exact mirror of IRbBitmap interface.

## Member Function Documentation

HRESULT IRdBitmapDisp::Clear | ( | void |  | ) |

Clear all data in the bitmap. Create has to be called to use the bitmap.

        bitMap is an attribute created on Script Editor Attributes tab.

        bitMap is of type "Common Data Package/Bitmap Data".

        bitMap.Clear();

HRESULT IRdBitmapDisp::Create | ( | [in] RtDWORD | nWidth,
|  | [in] RtDWORD | nHeight,
|  | [in] RtPixelFormat | PixelFormat |
| ) |  |  |

Creates the internal buffers of the bitmap and prepares the bitmap for the use.

Parameters:

  | nWidth | [in] Specifies desired width of the bitmap.
  | nHeight | [in] Specifies height of the bitmap.
  | PixelFormat | [in] Specifies the pixel format of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | for invalid dimensions or format.
  | E_OUTOFMEMORY | if bitmap does not fit into the memory.

        bitMap.Create(width, height, format); // format as number

HRESULT IRdBitmapDisp::CreateEx | ( | [in] RtDWORD | nWidth,
|  | [in] RtDWORD | nHeight,
|  | [in] BSTR | bsFormat |
| ) |  |  |

Creates the internal buffers of the bitmap and prepares the bitmap for the use.

Parameters:

  | nWidth | [in] Specifies desired width of the bitmap.
  | nHeight | [in] Specifies height of the bitmap.
  | bsFormat | [in] Specifies the pixel format of the bitmap in string form.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | for invalid dimensions or format
  | E_OUTOFMEMORY | if bitmap does not fit into the memory

        var outBitMap = System.CreateDO('Common Data Package/Bitmap Data');
        outBitMap.CreateEx( sizeX, sizeY, 'A8R8G8B8' );  //standard 32bit unsigned ARGB

HRESULT IRdBitmapDisp::ConvertFormat | ( | [in] RtPixelFormat | pFormat | ) |

Convert bitmap from one format to another.

Parameters:

  | pFormat | [in] Specifies the new format of the bitmap.

Return values:

  | E_FAIL | is returned if bitmap is empty.
  | E_INVALIDARG | is returned if new format type is not valid.
  | E_OUTOFMEMORY | is returned if new bitmap does not fit into the memory.

Returns:
  Standard HRESULT processing can be applied to the result.

        bitMap.ConvertFormat(2);

HRESULT IRdBitmapDisp::GetHeader | ( | [out] RtDWORD * | pdwWidth,
|  | [out] RtDWORD * | pdwHeight,
|  | [out] RtPixelFormat * | pFormat |
| ) |  |  |

Return the header information of the bitmap.

Parameters:

  | pdwWidth | [out] Is filled with the width of the bitmap. Specify NULL if you do not require this information.
  | pdwHeight | [out] Is filled with the height of the bitmap. Specify NULL if you do not require this information.
  | pFormat | [out] Is filled with the format of the bitmap. Specify NULL if you do not require this information.

Returns:
  Standard HRESULT processing can be applied to the result.

        var a = bitMap.GetHeader(width, height, format);

HRESULT IRdBitmapDisp::GetSizeX | ( | [out, retval] RtDWORD * | pOut | ) |

Get the horizontal size.

Returns:
  pOut [out, retval] Is filled with the horizontal size of the bitmap.

  Standard HRESULT processing can be applied to the result.

        var sizeX = bitMap.GetSizeX();

HRESULT IRdBitmapDisp::GetSizeY | ( | [out, retval] RtDWORD * | pOut | ) |

Get the vertical size

Returns:
  pOut [out, retval] Is filled with the vertical size of the bitmap.

  Standard HRESULT processing can be applied to the result.

        var sizeY = bitMap.GetSizeY();

HRESULT IRdBitmapDisp::GetFormatString | ( | [out, retval] BSTR * | pOut | ) |

Get the pixel format in a string value.

Returns:
  pOut [out, retval] Is filled with the format of the bitmap in a string descriptor for usage in scripts.

  Standard HRESULT processing can be applied to the result.

        var bmpFstr = bitMap.GetFormatString();

HRESULT IRdBitmapDisp::GetFormat | ( | [out, retval] RtPixelFormat * | pOut | ) |

Get the pixel format of the bitmap in numeric form:

- 0 = Unknown format.
- 1 = A8R8G8B8 (Standard 32bit unsigned ARGB).
- 2 = A16B16G16R16 (64bit unsigned ARGB).
- 3 = A32fB32fG32fR32f (128bit ARGB signed float).
- 4 = R8 (8bit unsigned R channel).
- 5 = R16 (16bit unsigned R channel).
- 6 = R32f 32bit signed float R channel.

Returns:
  pOut [out, retval] Is filled with the pixel format of the bitmap.

  Standard HRESULT processing can be applied to the result.

        var bmpFormat = bitMap.GetFormat();

HRESULT IRdBitmapDisp::GetFormatNumberFromString | ( | [in] BSTR | bsFormat,
|  | [out, retval] RtPixelFormat * | pOut |
| ) |  |  |

Convert string format to the enumeration number.

Parameters:

  | bsFormat | [in] Specifies the pixel format in the string.

Returns:
  pOut [out, retval] Is filled with the format of the bitmap that can be used in Create method.

  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid format.

        var bmpFFStr = bitMap.GetFormatNumberFromString(bmpFstr);

HRESULT IRdBitmapDisp::GetFormatStringFromNumber | ( | [in] RtPixelFormat | Format,
|  | [out, retval] BSTR * | pOut |
| ) |  |  |

Get the pixel format string from a number.

Parameters:

  | Format | [in] Specifies the pixel format in a number form.

Returns:
  pOut [out, retval] Is filled with the format of the bitmap in the string form.

  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid format.

        var bmpFstrNum = bitMap.GetFormatStringFromNumber(bmpFFStr);

HRESULT IRdBitmapDisp::GetPixel | ( | [in] RtDWORD | dwPositionX,
|  | [in] RtDWORD | dwPositionY,
|  | [in] IDispatch * | pOutValue |
| ) |  |  |

Return pixel color at given position.

Parameters:

  | dwPositionX | [in] Specifies the horizontal position of a pixel.
  | dwPositionY | [in] Specifies the vertical position of a pixel.
  | pOutValue | [in] Passed Color object is filled with color.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for position out of bounds.
  | E_FAIL | is returned also for unknown format and when lock failed.

        var pColor = System.CreateDO('Common Data Package/Color Data');
        var sizeX = bitMap.GetSizeX();
        var sizeY = bitMap.GetSizeY();
        bitMap.GetPixel(sizeX-1,sizeY-1,pColor);
        var alpha = pColor.GetAlpha();
        var red = pColor.GetRed();
        var green = pColor.GetGreen();
        var blue = pColor.GetBlue();

HRESULT IRdBitmapDisp::SetPixel | ( | [in] RtDWORD | dwPositionX,
|  | [in] RtDWORD | dwPositionY,
|  | [in] IDispatch * | pInValue |
| ) |  |  |

Set pixel color at given position.

Parameters:

  | dwPositionX | [in] Specifies the horizontal position of a pixel.
  | dwPositionY | [in] Specifies the vertical position of a pixel.
  | pInValue | [in] Specifies new color of the pixel.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for position out of bounds.
  | E_FAIL | is returned also for unknown format and when lock failed.

        var pColor = System.CreateDO('Common Data Package/Color Data');
        pColor.SetAlpha(Math.Random());
        pColor.SetRed(Math.Random());
        pColor.SetGreen(Math.Random());
        pColor.SetBlue(Math.Random());
        bitMap.SetPixel(x,y,pColor);

HRESULT IRdBitmapDisp::GetPixelCOLORREF | ( | [in] RtDWORD | dwPositionX,
|  | [in] RtDWORD | dwPositionY,
|  | [out, retval] COLORREF * | pOutValue |
| ) |  |  |

Return pixel at given position in the COLORREF format.

Parameters:

  | dwPositionX | [in] Specifies the horizontal position of a pixel.
  | dwPositionY | [in] Specifies the vertical position of a pixel.

Returns:
  pOutValue [out, retval] Returns the COLORREF value for the specified pixel.

  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for position out of bounds.
  | E_FAIL | is returned also for unknown format and when lock failed.

        var color = bitMap.GetPixelCOLORREF(x,y);

HRESULT IRdBitmapDisp::LockBitmap | ( |  | ) |

Lock the bitmap - access to methods from other threads will not be possible until UnlockBitmap is called.

Warning:
  Use CRsBitmapLock from Utils for safe lock and unlock.

Returns:
  Standard HRESULT processing can be applied to the result.

        bitMap.LockBitmap();

HRESULT IRdBitmapDisp::UnlockBitmap | ( |  | ) |

Unlock the bitmap after previous call to LockBitmap.

Warning:
  Use CRsBitmapLock from Utils for safe lock and unlock

Returns:
  Standard HRESULT processing can be applied to the result.

        bitMap.UnlockBitmap();

HRESULT IRdBitmapDisp::LoadFromFile | ( | [in] BSTR | FileName | ) |

This method is used to load image from a file. Previous bitmap contents are discarded.

Parameters:

  | FileName | [in] Specifies the file name (including optional path) for load.

Returns:
  Standard HRESULT processing can be applied to the result.

  E_INVALIDARG for unsupported format.

        var FileName = params.ConValue('FileName');
        var ImageLoaded = System.CreateDO("Common Data Package/Bitmap Data");
        ImageLoaded.LoadFromFile(FileName);
        params.ConValue("ImageLoaded") = ImageLoaded;

HRESULT IRdBitmapDisp::GetFileName | ( | [out, retval] BSTR * | pFileName | ) |

Get filename of the bitmap if it was loaded from file.

Returns:
  pFileName [out, retval] Is filled with the name of the file.

  Standard HRESULT processing can be applied to the result.

Return values:

  | S_OK | if file was loaded from file.
  | S_FALSE | if file was not loaded from file.

        System.Alert(ImageLoaded.GetFileName());

HRESULT IRdBitmapDisp::SetIsFromFile | ( | [in] RtBool | bIsFromFile,
|  | [in] BSTR | bstrFileName |
| ) |  |  |

Set IsFromFile flag and filename of the bitmap (useful when you modified the bitmap but still want to keep track of origin filename).

Parameters:

  | bIsFromFile | [in] Specifies if bitmap was loaded from file (TRUE) or not (FALSE).
  | bstrFileName | [in] Specifies the filename of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        ImageLoaded.SetIsFromFile(true, ImageLoaded.GetFileName());

HRESULT IRdBitmapDisp::SaveToFile | ( | [in] RtBitmapFileFormat | Format,
|  | [in] BSTR | FileName |
| ) |  |  |

This method is used to save image to a file.

Parameters:

  | Format | [in] Specifies the format of a bitmap.
  | FileName | [in] Specifies the target filename of a bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        newFileName = ImageLoaded.GetFileName();
     ImageLoaded.SetIsFromFile(true, ImageLoaded.GetFileName());
     ImageLoaded.SaveToFile(ImageLoaded.GetFormat(), newFileName);

HRESULT IRdBitmapDisp::Resize | ( | [in] RtDWORD | dwWidth,
|  | [in] RtDWORD | dwHeight |
| ) |  |  |

This method is used to resize the bitmap.

Parameters:

  | dwWidth | [in] Specifies new width of the bitmap.
  | dwHeight | [in] Specifies new height of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        var sizeX = ImageLoaded.GetSizeX();
     var sizeY = ImageLoaded.GetSizeY();
     ImageLoaded.Resize(sizeX + 64, sizeY + 64);
     System.Alert(ImageLoaded.GetSizeX() + "  " + ImageLoaded.GetSizeY());

HRESULT IRdBitmapDisp::GetSupportedFormatCount | ( | [out, retval] DWORD * | dwFormatCount | ) |

Return the number of supported loadable formats for enumeration through GetSupportedFormatMasks and GetSupportedFormatName.

Returns:
  dwFormatCount [out, retval] Is filled with number of loadable formats.

  Standard HRESULT processing can be applied to the result.

        ImageLoaded.GetSupportedFormatCount();

HRESULT IRdBitmapDisp::GetSupportedFormatMasks | ( | [in] DWORD | dwFormat,
|  | [out, retval] BSTR * | bsMasks |
| ) |  |  |

Return the information about supported formats.

Parameters:

  | dwFormat | [in] Specifies the format index.

Returns:
  bsMasks [out, retval] Is filled with the possible file masks separated by ; (i.e. *.gif or *.jpg;*.jpeg)

  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid index.

        var stringA = ImageLoaded.GetSupportedFormatMasks(ImageLoaded.GetFormat());

HRESULT IRdBitmapDisp::GetSupportedFormatName | ( | [in] DWORD | dwFormat,
|  | [out, retval] BSTR * | bsFormatName |
| ) |  |  |

Return the information about supported format.

Parameters:

  | dwFormat | [in] Specifies the format index.

Returns:
  bsFormatName [out, retval] Is filled with the name of the format

  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid index.

        var info = ImageLoaded.GetSupportedFormatName(1); // index to list of supported formats

HRESULT IRdBitmapDisp::IsEqual | ( | [in] IDispatch * | pBitmap,
|  | [out, retval] BOOL * | bEqualityResult |
| ) |  |  |

Checks bitmap for equality with other bitmap.

Return S_OK if bitmaps are equal and return S_FALSE if they are not equal.

Parameters:

  | pBitmap | [in] Specifies the other bitmap in the test.

Returns:
  bEqualityResult [out, retval] Optional BOOL parameter is provided for script usage - if not NULL it is filled with TRUE for equal bitmaps and FALSE for unequal.

  Standard HRESULT processing can be applied to the result.

Return values:

  | S_OK | for equal bitmaps.
  | S_FALSE | for non equal bitmaps.
  | E_XXX | error code should be also considered as non-equality result.

        var bitMap = params.ConValue('bitMap');
        var bitMap1 = params.ConValue('bitMap1');
        var variableA = bitMap.IsEqual(bitMap1);
        params.ConValue('variableA') = variableA; // returns 1 for true and 0 for false

HRESULT IRdBitmapDisp::GetImageSizeFromFile | ( | [in] BSTR | FileName,
|  | [out, retval] VARIANT * | pvRetInfo |
| ) |  |  |

Return Width and Height of the file on disk (if supported)

Parameters:

  | FileName | [in] Specifies the name (and path) of a file to return size of.

Returns:
  pvRetInfo [out, retval] Returns IRsReturn object filled with the width and height of the bitmap in file:
  - width - width of the bitmap.
  - height - height of the bitmap.

  Standard HRESULT processing can be applied to the result.

Return values:

  | S_OK | if image file was found and size was returned.

Example:

            BmpSize = ThisBitmap.GetImageSizeFromFile('.\TestBitmap.png');
            width = BmpSize.Param("width");
            height = BmpSize.Param("height");

HRESULT IRdBitmapDisp::GetDownsampledFlag | ( | [out, retval] RtBool * | pVal | ) |

Get downsampled flag.

Returns:
  pVal [out, retval] Is filled with true if texture has been down-sampled after load from file.

  Standard HRESULT processing can be applied to the result.

        outBitMap.SetDownsampledFlag(1);
        var flag = outBitMap.GetDownsampledFlag();
        System.Alert(flag);

HRESULT IRdBitmapDisp::SetDownsampledFlag | ( | [in] RtBool | newVal | ) |

Set down-sampled flag.

Parameters:

  | newVal | [in] Specifies the value of down-sampling.

Returns:
  Standard HRESULT processing can be applied to the result.

        ImageLoaded.SetDownsampledFlag(1); // number represents downsample value

HRESULT IRdBitmapDisp::SaveToFileEx | ( | [in] RtBitmapFileFormat | Format,
|  | [in] BSTR | FileName |
| ) |  |  |

This method is used to save image to a file using external image library (including alpha channel if format supports it.

Parameters:

  | Format | [in] Specifies the format of a bitmap.
  | FileName | [in] Specifies the target filename of a bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

Remarks:
  Require developer explanation of this method.

HRESULT IRdBitmapDisp::Clear | ( | void |  | ) |

Clear all data in the bitmap. Create has to be called to use the bitmap.

        bitMap is an attribute created on Script Editor Attributes tab.

        bitMap is of type "Common Data Package/Bitmap Data".

        bitMap.Clear();

HRESULT IRdBitmapDisp::Create | ( | [in] RtDWORD | nWidth,
|  | [in] RtDWORD | nHeight,
|  | [in] RtPixelFormat | PixelFormat |
| ) |  |  |

Creates the internal buffers of the bitmap and prepares the bitmap for the use.

Parameters:

  | nWidth | specifies desired width of the bitmap.
  | nHeight | specifies height of the bitmap.
  | PixelFormat | specifies the pixel format of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | for invalid dimensions or format.
  | E_OUTOFMEMORY | if bitmap does not fit into the memory.

        bitMap.Create(width, height, format); // format as number

HRESULT IRdBitmapDisp::CreateEx | ( | [in] RtDWORD | nWidth,
|  | [in] RtDWORD | nHeight,
|  | [in] BSTR | bsFormat |
| ) |  |  |

Creates the internal buffers of the bitmap and prepares the bitmap for the use.

Parameters:

  | nWidth | specifies desired width of the bitmap.
  | nHeight | specifies height of the bitmap.
  | bsFormat | specifies the pixel format of the bitmap in string form.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | for invalid dimensions or format
  | E_OUTOFMEMORY | if bitmap does not fit into the memory

        var outBitMap = System.CreateDO('Common Data Package/Bitmap Data');
        outBitMap.CreateEx( sizeX, sizeY, 'A8R8G8B8' );  //standard 32bit unsigned ARGB

HRESULT IRdBitmapDisp::ConvertFormat | ( | [in] RtPixelFormat | pFormat | ) |

Convert bitmap from one format to another.

Parameters:

  | pFormat | specifies the new format of the bitmap.

Return values:

  | E_FAIL | is returned if bitmap is empty
  | E_INVALIDARG | is returned if new format type is not valid
  | E_OUTOFMEMORY | is returned if new bitmap does not fit into the memory

Returns:
  Standard HRESULT processing can be applied to the result.

        bitMap.ConvertFormat(2);

HRESULT IRdBitmapDisp::GetHeader | ( | [out] RtDWORD * | pdwWidth,
|  | [out] RtDWORD * | pdwHeight,
|  | [out] RtPixelFormat * | pFormat |
| ) |  |  |

Return the header information of the bitmap.

Parameters:

  | pdwWidth | is filled with the width of the bitmap. Specify NULL if you do not require this information.
  | pdwHeight | is filled with the height of the bitmap. Specify NULL if you do not require this information.
  | pFormat | is filled with the format of the bitmap. Specify NULL if you do not require this information.

Returns:
  Standard HRESULT processing can be applied to the result.

        var a = bitMap.GetHeader(width, height, format);

HRESULT IRdBitmapDisp::GetSizeX | ( | [out, retval] RtDWORD * | pOut | ) |

Get the horizontal size.

Parameters:

  | pOut | is filled with the horizontal size of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        var sizeX = bitMap.GetSizeX();

HRESULT IRdBitmapDisp::GetSizeY | ( | [out, retval] RtDWORD * | pOut | ) |

Get the vertical size

Parameters:

  | pOut | is filled with the vertical size of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        var sizeY = bitMap.GetSizeY();

HRESULT IRdBitmapDisp::GetFormatString | ( | [out, retval] BSTR * | pOut | ) |

Get the pixel format in a string

Parameters:

  | pOut | is filled with the format of the bitmap in a string descriptor for usage in scripts.

Returns:
  Standard HRESULT processing can be applied to the result.

        var bmpFstr = bitMap.GetFormatString();

HRESULT IRdBitmapDisp::GetFormat | ( | [out, retval] RtPixelFormat * | pOut | ) |

Get the pixel format

Parameters:

  | pOut | is filled with the format of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        var bmpFormat = bitMap.GetFormat();

HRESULT IRdBitmapDisp::GetFormatNumberFromString | ( | [in] BSTR | bsFormat,
|  | [out, retval] RtPixelFormat * | pOut |
| ) |  |  |

Convert string format to the enumeration number

Parameters:

  | bsFormat | specifies the pixel format in the string.
  | pOut | is filled with the format of the bitmap that can be used in Create method.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid format.

        var bmpFFStr = bitMap.GetFormatNumberFromString(bmpFstr);

HRESULT IRdBitmapDisp::GetFormatStringFromNumber | ( | [in] RtPixelFormat | Format,
|  | [out, retval] BSTR * | pOut |
| ) |  |  |

Get the pixel format string from a number.

Parameters:

  | Format | specifies the pixel format in a number form.
  | pOut | is filled with the format of the bitmap in the string form.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid format.

        var bmpFstrNum = bitMap.GetFormatStringFromNumber(bmpFFStr);

HRESULT IRdBitmapDisp::GetPixel | ( | [in] RtDWORD | dwPositionX,
|  | [in] RtDWORD | dwPositionY,
|  | [in] IDispatch * | pOutValue |
| ) |  |  |

Return pixel color at given position.

Parameters:

  | dwPositionX | specifies the horizontal position of a pixel
  | dwPositionY | specifies the vertical position of a pixel
  | pOutValue | passed Color object is filled with color.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for position out of bounds.
  | E_FAIL | is returned also for unknown format and when lock failed.

        var pColor = System.CreateDO('Common Data Package/Color Data');
        var sizeX = bitMap.GetSizeX();
        var sizeY = bitMap.GetSizeY();
        bitMap.GetPixel(sizeX-1,sizeY-1,pColor);
        var alpha = pColor.GetAlpha();
        var red = pColor.GetRed();
        var green = pColor.GetGreen();
        var blue = pColor.GetBlue();

HRESULT IRdBitmapDisp::SetPixel | ( | [in] RtDWORD | dwPositionX,
|  | [in] RtDWORD | dwPositionY,
|  | [in] IDispatch * | pInValue |
| ) |  |  |

Set pixel color at given position

Parameters:

  | dwPositionX | specifies the horizontal position of a pixel
  | dwPositionY | specifies the vertical position of a pixel
  | pInValue | specifies new color of the pixel.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for position out of bounds.
  | E_FAIL | is returned also for unknown format and when lock failed.

        var pColor = System.CreateDO('Common Data Package/Color Data');
        pColor.SetAlpha(Math.Random());
        pColor.SetRed(Math.Random());
        pColor.SetGreen(Math.Random());
        pColor.SetBlue(Math.Random());
        bitMap.SetPixel(x,y,pColor);

HRESULT IRdBitmapDisp::GetPixelCOLORREF | ( | [in] RtDWORD | dwPositionX,
|  | [in] RtDWORD | dwPositionY,
|  | [out, retval] COLORREF * | pOutValue |
| ) |  |  |

Return pixel at given position in the COLORREF format.

Parameters:

  | dwPositionX | specifies the horizontal position of a pixel
  | dwPositionY | specifies the vertical position of a pixel
  | pOutValue | passed Color object is filled with color.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for position out of bounds.
  | E_FAIL | is returned also for unknown format and when lock failed.

Remarks:
  Should x and y be in but COLORREF be an out?

        var color = bitMap.GetPixelCOLORREF(x,y);

HRESULT IRdBitmapDisp::LockBitmap | ( |  | ) |

Lock the bitmap - access to methods from other threads will not be possible until UnlockBitmap is called.

Warning:
  Use CRsBitmapLock from Utils for safe lock and unlock.

Returns:
  Standard HRESULT processing can be applied to the result.

        bitMap.LockBitmap();

HRESULT IRdBitmapDisp::UnlockBitmap | ( |  | ) |

Unlock the bitmap after previous call to LockBitmap.

Warning:
  Use CRsBitmapLock from Utils for safe lock and unlock

Returns:
  Standard HRESULT processing can be applied to the result.

        bitMap.UnlockBitmap();

HRESULT IRdBitmapDisp::LoadFromFile | ( | [in] BSTR | FileName | ) |

This method is used to load image from a file. Previous bitmap contents are discarded.

Parameters:

  | FileName | specifies the file name (including optional path) for load.

Returns:
  Standard HRESULT processing can be applied to the result.

  E_INVALIDARG for unsupported format.

        var FileName = params.ConValue('FileName');
        var ImageLoaded = System.CreateDO("Common Data Package/Bitmap Data");
        ImageLoaded.LoadFromFile(FileName);
        params.ConValue("ImageLoaded") = ImageLoaded;

HRESULT IRdBitmapDisp::GetFileName | ( | [out, retval] BSTR * | pFileName | ) |

Get filename of the bitmap if it was loaded from file.

Parameters:

  | pFileName | is filled with the name of the file.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | S_OK | if file was loaded from file
  | S_FALSE | if file was not loaded from file.

        System.Alert(ImageLoaded.GetFileName());

HRESULT IRdBitmapDisp::SetIsFromFile | ( | [in] RtBool | bIsFromFile,
|  | [in] BSTR | bstrFileName |
| ) |  |  |

Set IsFromFile flag and filename of the bitmap (useful when you modified the bitmap but still want to keep track of origin filename)

Parameters:

  | bIsFromFile | specifies if bitmap was loaded from file (TRUE) or not (FALSE)
  | bstrFileName | specifies the filename of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        ImageLoaded.SetIsFromFile(true, ImageLoaded.GetFileName());

HRESULT IRdBitmapDisp::SaveToFile | ( | [in] RtBitmapFileFormat | Format,
|  | [in] BSTR | FileName |
| ) |  |  |

This method is used to save image to a file.

Parameters:

  | Format | specifies the format of a bitmap.
  | FileName | specifies the target filename of a bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        newFileName = ImageLoaded.GetFileName();
     ImageLoaded.SetIsFromFile(true, ImageLoaded.GetFileName());
     ImageLoaded.SaveToFile(ImageLoaded.GetFormat(), newFileName);

HRESULT IRdBitmapDisp::Resize | ( | [in] RtDWORD | dwWidth,
|  | [in] RtDWORD | dwHeight |
| ) |  |  |

This method is used to resize the bitmap.

Parameters:

  | dwWidth | specifies new width of the bitmap.
  | dwHeight | specifies new height of the bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

        var sizeX = ImageLoaded.GetSizeX();
     var sizeY = ImageLoaded.GetSizeY();
     ImageLoaded.Resize(sizeX + 64, sizeY + 64);
     System.Alert(ImageLoaded.GetSizeX() + "  " + ImageLoaded.GetSizeY());

HRESULT IRdBitmapDisp::GetSupportedFormatCount | ( | [out, retval] DWORD * | dwFormatCount | ) |

Return the number of supported loadable formats for enumeration through GetSupportedFormatMasks and GetSupportedFormatName

Parameters:

  | dwFormatCount | is filled with number of loadable formats.

Returns:
  Standard HRESULT processing can be applied to the result.

        ImageLoaded.GetSupportedFormatCount();

HRESULT IRdBitmapDisp::GetSupportedFormatMasks | ( | [in] DWORD | dwFormat,
|  | [out, retval] BSTR * | bsMasks |
| ) |  |  |

Return the information about supported format

Parameters:

  | dwFormat | specifies the format index.
  | bsMasks | is filled with the possible file masks separated by ; (i.e. *.gif or *.jpg;*.jpeg)

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid index.

        var stringA = ImageLoaded.GetSupportedFormatMasks(ImageLoaded.GetFormat());

HRESULT IRdBitmapDisp::GetSupportedFormatName | ( | [in] DWORD | dwFormat,
|  | [out, retval] BSTR * | bsFormatName |
| ) |  |  |

Return the information about supported format

Parameters:

  | dwFormat | specifies the format index.
  | bsFormatName | is filled with the name of the format

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | E_INVALIDARG | is returned for invalid index.

        var info = ImageLoaded.GetSupportedFormatName(1); // index to list of supported formats

HRESULT IRdBitmapDisp::IsEqual | ( | [in] IDispatch * | pBitmap,
|  | [out, retval] BOOL * | bEqualityResult |
| ) |  |  |

Checks bitmap for equality with other bitmap. Return S_OK if bitmaps are equal and return S_FALSE if they are not equal.

Parameters:

  | pBitmap | specifies the other bitmap in the test.
  | bEqualityResult | Optional BOOL parameter is provided for script usage - if not NULL it is filled with TRUE for equal bitmaps and FALSE for unequal.

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | S_OK | for equal bitmaps.
  | S_FALSE | for non equal bitmaps.
  | E_XXX | error code should be also considered as non-equality result.

        var bitMap = params.ConValue('bitMap');
        var bitMap1 = params.ConValue('bitMap1');
        var variableA = bitMap.IsEqual(bitMap1);
        params.ConValue('variableA') = variableA; // returns 1 for true and 0 for false

HRESULT IRdBitmapDisp::GetImageSizeFromFile | ( | [in] BSTR | FileName,
|  | [out, retval] VARIANT * | pvRetInfo |
| ) |  |  |

Return Width and Height of the file on disk (if supported)

Parameters:

  | FileName | specifies the name (and path) of a file to return size
  | pvRetInfo | Returns IRsReturn object filled with the width and height of the bitmap in file width - width of the bitmap height - height of the bitmap

Returns:
  Standard HRESULT processing can be applied to the result.

Return values:

  | S_OK | if image file was found and size was returned.

Example:

            BmpSize = ThisBitmap.GetImageSizeFromFile('.\TestBitmap.png');
            width = BmpSize.Param("width");
            height = BmpSize.Param("height");

HRESULT IRdBitmapDisp::GetDownsampledFlag | ( | [out, retval] RtBool * | pVal | ) |

Get downsampled flag

Parameters:

  | pVal | is filled with true if texture has been down-sampled after load from file.

Returns:
  Standard HRESULT processing can be applied to the result.

        outBitMap.SetDownsampledFlag(1);
        var flag = outBitMap.GetDownsampledFlag();
        System.Alert(flag);

HRESULT IRdBitmapDisp::SetDownsampledFlag | ( | [in] RtBool | newVal | ) |

Set down-sampled flag.

Parameters:

  | newVal | specifies the value of down-sampling.

Returns:
  Standard HRESULT processing can be applied to the result.

        ImageLoaded.SetDownsampledFlag(1); // number represents downsample value

HRESULT IRdBitmapDisp::SaveToFileEx | ( | [in] RtBitmapFileFormat | Format,
|  | [in] BSTR | FileName |
| ) |  |  |

This method is used to save image to a file using external image library (including alpha channel if format supports it.

Parameters:

  | Format | specifies the format of a bitmap.
  | FileName | specifies the target filename of a bitmap.

Returns:
  Standard HRESULT processing can be applied to the result.

Remarks:
  Require developer explanation of this method.