LEADTOOLS Raster Imaging C DLL Help > Function References > L_SetTag |
#include "l_bitmap.h"
L_LTFIL_API L_INT L_SetTag(uTag, uType, uCount, pData)
L_UINT16 uTag; |
/* tag to identify the data in the TIFF file */ |
L_UINT16 uType; |
/* tagged data type */ |
L_UINT uCount; |
/* count of data items */ |
L_VOID* pData; |
/* pointer to the buffer containing the data */ |
Specifies a private tag and the tagged data to be saved in a TIFF file.
Parameter |
Description |
|
uTag |
Tag to identify the data in the TIFF file. Generally, you can specify a private tag in the range of 0x8000 to 0xFFFE. However, LEADTOOLS returns an error if you use any of the following registered tags: |
|
|
Value |
Meaning |
|
0x8298 |
Copyright comment |
|
0x8769 |
General Exif comments |
|
0x8825 |
Exif GPS comments |
|
|
LEADTOOLS does NOT return an error if you set: |
|
0x80A4 |
Annotation TIFF tag defined as ANNTAG_TIFF. |
uType |
Tagged data type. Valid values are: |
|
|
Value |
Meaning |
|
TAG_BYTE |
[1] Byte. |
|
TAG_ASCII |
[2] Byte in the range of 0 to 255. |
|
TAG_SBYTE |
[6] Byte used as signed number in the range of -128 to +127. |
|
TAG_UNDEFINED |
[7] Byte, with application-defined usage. |
|
TAG_SHORT |
[3] Two bytes, unsigned. |
|
TAG_SSHORT |
[8] Two bytes, signed. |
|
TAG_LONG |
[4] Four bytes, unsigned. |
|
TAG_SLONG |
[9] Four bytes, signed. |
|
TAG_RATIONAL |
[5] Eight bytes, used as a pair of unsigned long integers, where the first number is the numerator and the second is the denominator of a fraction. |
|
TAG_SRATIONAL |
[10] Eight bytes, used as a pair of signed long integers, where the first number is the numerator and the second is the denominator of a fraction. |
|
TAG_FLOAT |
[11] Four bytes used as a floating point number. |
|
TAG_DOUBLE |
[12] Eight bytes used as a double-precision floating point number. |
uCount |
Count of data items, based on the tagged data type. For example, if the buffer size is 16 and the data type is TAG_DOUBLE, the count is 2. |
|
pData |
Pointer to a buffer containing the data to be saved using the tag. |
Returns
SUCCESS |
The function was successful. |
< 1 |
An error occurred. Refer to Return Codes. |
Comments
This function copies the data from your buffer to an internally-allocated buffer. You should free your own buffer after calling this function. Any TIFF file that you save will include the tagged data until you clear the tag. LEADTOOLS keeps a list of tags in memory. The list contains all the tags set directly (by calling L_SetTag) or indirectly (by calling L_AnnSaveTag). All these tags will be saved unless you clear them. The way to clear a tag and remove it from the list is by calling L_SetTag(uTag, 0, 0, NULL). L_SetTag(0,0,0,NULL) will remove ALL the tags from the tag list.
For general information about TIFF tags, refer to Implementing TIFF Comments and Tags.
Note: |
When LEADTOOLS saves a TIFF/Exif image that contains comments and tags, the comments and tags will be written first, followed by the image data. This order is not configurable. |
|
To write tags to a TIFF file, use L_WriteFileTag or L_WriteFileTagMemory instead of using L_SetTag followed by L_SaveFile or L_SaveFileMemory. |
Required DLLs and Libraries
For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application. |
Platforms
Win32, x64, Linux.
See Also
Functions: |
L_GetTag, L_ReadFileTag, L_ReadFileTagMemory, L_AnnSaveTag, L_DeleteTag, L_ReadFileTags |
Topics: |
Example
This example specifies a tag for recording the position of a company logo on the image. It sets the tag with L_SetTag; tests the tag with L_GetTag; then saves a TIFF file with the new tag. For an example that reads this same tag from the file, refer to L_ReadFileTag.
#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName L_INT SetTagExample(pBITMAPHANDLE pBitmap) { L_INT nRet; L_TCHAR msgbuf[80]; /* buffer for the message string */ L_UINT16 LogoPosition = 0x8001; /* my private tag */ L_UINT16 TagType = TAG_SSHORT; /* tagged data type */ L_UINT32 TagCount = 4; /* count of data items */ L_INT TagData[] = {5, 5, 24, 37}; L_VOID * pTagData = &TagData; /* pointer to the buffer containing the data */ /* Set the tag data to be saved */ nRet = L_SetTag(LogoPosition, TagType, TagCount, pTagData); if(nRet != SUCCESS) return nRet; /* Clear the variables so that we can validate the data */ TagType = 0; TagCount = 0; TagData[0] = 0; TagData[1] = 0; TagData[2] = 0; TagData[3] = 0; /* Get the tag data that is ready to be saved */ nRet = L_GetTag(LogoPosition, &TagType, &TagCount, pTagData); if(nRet < SUCCESS) return nRet; /* Display a message showing the data */ if ((TagType == TAG_SSHORT) && (TagCount == 4)) { wsprintf(msgbuf, TEXT("X = %d\nY= %d\nWidth = %d\nHeight = %d"), ((L_INT *)pTagData)[0], ((L_INT *)pTagData)[1], ((L_INT *)pTagData)[2], ((L_INT *)pTagData)[3]); MessageBox (NULL, msgbuf, TEXT("Logo Position"), MB_OK); } /* Save the file with the tag */ nRet = L_SaveBitmap(MAKE_IMAGE_PATH(TEXT("TEST.TIF")), pBitmap, FILE_TIF, pBitmap->BitsPerPixel, 0, NULL); if(nRet != SUCCESS) return nRet; /* Clear the tag from memory */ nRet = L_SetTag(0, 0, 0, NULL); return SUCCESS; }