nn::y2r::CTR

Description

CTR namespace for Y2R (YUV to RGB conversion).
(This can also be written without the "::CTR" portion.)

Note about support for Sleep Mode:
If the system transitions to sleep during a Y2R conversion, it will forcibly suspend the conversion. Also, the conversion will not be restarted once the system recovers from sleep. To support the Y2R conversion during the transition to sleep, make sure that the system transitions to sleep only after conversion is complete and not when the IsBusyConversion function returns true or while it is waiting for the event object obtained with the GetTransferEndEvent function. If the system transitions to sleep when an event object returned by GetTransferEndEvent is waiting for an event, after the system recovers from sleep, the event object will not be signaled.

Note about transfer bug:
There is a bug with the Y2R hardware that causes hangs during data transfers. A workaround is therefore required.

Symptoms

A hangup occurs during Y2R conversion, which causes the transfer completion event obtained using the GetTransferEvent function not to be signaled.

Conditions for occurrence

If the camera and the Y2R hardware are used at the same time.
In addition, if a buffer error occurs during the transfer of camera data, and the timing of the nn::camera::CTR::SetReceiving part of the recovery process coincides with a certain portion of the Y2R data transfer operation.

These conditions occur only in rare situations, so the occurrence of a camera buffer error won't always cause this bug to occur. The bug will not occur if the camera and Y2R hardware are not used at the same time.

Workaround

Insert a timeout when waiting for the transfer completion event obtained using the GetTransferEndEvent function. The timeout should be set to a value longer than the time required for Y2R conversion. The time required for conversion depends on the size of the input image and the output format. A VGA image being output as 16-bit RGB will take about 13 milliseconds, and a VGA image being output as 24-bit RGB will take about 16 milliseconds. When this error occurs, you can call StopConversion to forcibly stop the conversion, after which you can resume use of Y2R.

The chances of this error occurring are proportional to the frequency of camera buffer errors. It is therefore recommended that the camera be used in situations in which it is unlikely for a buffer error to occur. If buffer errors are occurring with high frequency, reduce the frame rate of the camera. Additionally, set the thread in which nn::camera::CTR::SetReceiving is called to high priority.

Classes

`nn::y2r::CTR::ResultIsSleeping`	Indicates that the Y2R library cannot be used because the system is sleeping.

Structures

`nn::y2r::CTR::DitheringWeightParams`	Structure representing a dithering pattern.
`nn::y2r::CTR::PackageParameter`	Structure used for batch parameter configuration.

Enumerated Types

	`InputFormat`	Enumerated type that indicates the input mode.
	`OutputFormat`	Enumerated type that indicates the output pixel format.
	`Rotation`	Enumerated type that indicates the output buffer rotation.
	`BlockAlignment`	Enumerated type that indicates an array of output buffers.
	`StandardCoefficient`	Enumerated type that indicates the standard conversion coefficient.

Functions

	`Initialize`	Initializes the Y2R library.
	`Finalize`	Finalizes the Y2R library.
	`SetInputFormat`	Sets the input format.
	`GetInputFormat`	Gets the input format.
	`SetOutputFormat`	Sets the output format.
	`GetOutputFormat`	Gets the output format.
	`SetRotation`	Sets the rotation angle of the output buffer.
	`GetRotation`	Gets the rotation angle of the output buffer.
	`SetBlockAlignment`	Sets the alignment of the data in the output buffer.
	`GetBlockAlignment`	Gets the alignment of the data in the output buffer.
	`SetSpacialDithering`	Enables or disables spacial dithering of the output image.
	`GetSpacialDithering`	Checks whether spacial dithering of the output image is enabled.
	`SetTemporalDithering`	Enables or disables temporal dithering of the output image. The initial value is `false`.
	`GetTemporalDithering`	Checks whether temporal dithering of the output image is enabled. The initial value is `false`.
	`SetTransferEndInterrupt`	Enables or disables data transfer completion interrupts. The initial value is `true`.
	`GetTransferEndInterrupt`	Checks whether data transfer completion interrupts are enabled.
	`GetTransferEndEvent`	Gets the event that is used to detect the occurrence of a data transfer completion interrupt.
	`SetSendingY`	Configures writing of Y data. The actual transfer operation takes place after `StartConversion` is called.
	`SetSendingU`	Configures writing of U data. The actual transfer operation takes place after `StartConversion` is called.
	`SetSendingV`	Configures writing of V data. The actual transfer operation takes place after `StartConversion` is called.
	`SetSendingYuv`	Configures writing of YUV data. The actual transfer operation takes place after `StartConversion` is called.
	`IsFinishedSendingYuv`	Determines whether writing of YUV data has finished.
	`IsFinishedSendingY`	Determines whether writing of Y data has finished.
	`IsFinishedSendingU`	Determines whether writing of U data has finished.
	`IsFinishedSendingV`	Determines whether writing of V data has finished.
	`SetReceiving`	Configures loading of RGB data. The actual transfer operation takes place after `StartConversion` is called.
	`IsFinishedReceiving`	Checks whether loading has finished.
	`SetInputLineWidth`	Sets the width of a single line of input data.
	`GetInputLineWidth`	Gets the width of a single line of input data.
	`SetInputLines`	Sets the number of vertical lines of input data.
	`GetInputLines`	Gets the number of vertical lines of input data.
	`GetOutputFormatBytes`	Calculates the number of bytes per pixel in the specified output format.
	`GetOutputBlockSize`	Calculates the size of the output block.
	`GetOutputImageSize`	Calculates the size of the output image.
	`SetStandardCoefficient`	Sets the standard conversion coefficients.
	`SetAlpha`	Sets the alpha value for a 32-bit RGB or RGB555 output format.
	`GetAlpha`	Gets the alpha value for a 32-bit RGB or RGB555 output format.
	`SetDitheringWeightParams`	Sets the dithering pattern.
	`GetDitheringWeightParams`	Gets the dithering pattern.
	`StartConversion`	Starts conversion.
	`StopConversion`	Forcibly stops conversion.
	`IsBusyConversion`	Checks whether conversion is underway.
	`SetPackageParameter`	Configures the Y2R settings all at once.

Revision History

2010/11/10: Added descriptions to the symptoms and workaround for the transfer bug.
2010/10/30: Added an explanation of sleep transition and recovery behaviors and methods for supporting them.
2010/01/07: Initial version.