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 Sleep Mode, implement your application to transition to sleep only after Y2R conversion is complete and not while conversion is in progress. (That is, not while the nn::y2r::CTR::IsBusyConversion function returns true or while control is waiting for the event obtained by the nn::y2r::CTR::GetTransferEndEvent function.) Note that if the application transitions to sleep while waiting for an event obtained by the nn::y2r::CTR::GetTransferEndEvent function, then the event will not be signaled after the system recovers from sleep. Be extremely careful to avoid this.

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

Symptoms

The system freezes during Y2R conversion, so the the transfer completion event obtained by the nn::y2r::CTR::GetTransferEvent function is not signaled and the nn::y2r::CTR::IsBusyConversion function does not return true.

Conditions for occurrence

Cameras and Y2R hardware are used at the same time
AND, a buffer error occurs during the transfer of camera data and during error recovery the nn::y2r::CTR::SetReceiving function processing 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

Enter timeouts when waiting for the transfer completion event being obtained by the nn::y2r::CTR::GetTransferEndEvent function and when waiting for the nn::y2r::CTR::IsBusyConversion function to return true. 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. Also note that you can call the nn::y2r::CTR::StopConversion function to forcibly stop the conversion when this bug occurs, after which you can resume use of Y2R.

The chances of this bug occurring are proportional to the frequency of camera buffer errors. It is therefore recommended that the cameras be used under conditions 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 cameras. Also, set the thread in which the nn::y2r::CTR::SetReceiving function is called to a relatively 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 the `StartConversion` function is called.
	`SetSendingU`	Configures writing of U data. The actual transfer operation takes place after the `StartConversion` function is called.
	`SetSendingV`	Configures writing of V data. The actual transfer operation takes place after the `StartConversion` function is called.
	`SetSendingYuv`	Configures writing of YUV data. The actual transfer operation takes place after the `StartConversion` function 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 the `StartConversion` function 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.
	`GetPackageParameter`	Gets the Y2R settings all at once.

Revision History

2011/06/24: Added functions that have problems when the transfer bug occurs.
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.

CONFIDENTIAL